How-to: Set Up a Webhook Endpoint

To start receiving webhook notifications from a Circle product, expose a subscriber endpoint that can receive HTTP requests from Circle, then register that endpoint as a subscriber to the events you care about. The endpoint setup is the same across products. The subscription API differs per product.

Set up a subscriber endpoint

Expose a publicly accessible HTTPS endpoint that:

Is reachable from the public internet.
Handles both HEAD and POST requests. Circle uses HEAD to validate the URL when you create or update a subscription, and POST to deliver notifications.
Responds to POST requests with a 200 OK status code so Circle treats the delivery as successful. Any other status causes Circle to retry the notification.

To test before deploying a real endpoint, generate a temporary URL with webhook.site and use it as your subscriber endpoint.

Allowlist Circle's source IP addresses

Configure your firewall, load balancer, or cloud security groups so your endpoint only trusts webhook requests from Circle’s source IP addresses. This blocks unauthenticated traffic at the network edge as a layer of defense in addition to signature verification. Allowlist the IP addresses for each product you integrate with separately.Wallets, Contracts, and Gateway share the same webhook delivery infrastructure:

54.243.112.156
100.24.191.35
54.165.52.248
54.87.106.46

Circle Payments Network (CPN):

35.169.154.32
3.90.127.28
3.230.111.7
54.88.227.75

Stablecoin FX (StableFX):

3.230.111.7
3.90.127.28
35.169.154.32
54.88.227.75

Subscribe to notifications

Register your endpoint as a subscriber by calling the Create Subscription endpoint for your product. Select your product below for the request shape:

Wallets and Contracts
CPN
StableFX
Circle Mint
Gateway

Wallets and Contracts share the same subscription endpoint. See the Create Subscription reference for Wallets or Contracts for the full schema.

curl --request POST \
  --url https://api.circle.com/v2/notifications/subscriptions \
  --header "Authorization: Bearer $CIRCLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "endpoint": "https://your-app.example.com/webhooks",
    "notificationTypes": ["*"]
  }'

Example response:

{
  "data": {
    "id": "b3d9d2d5-4c12-4946-a09d-953e82fae2b0",
    "name": "Transactions Webhook",
    "endpoint": "https://your-app.example.com/webhooks",
    "enabled": true,
    "createDate": "2026-01-15T21:47:35.107250Z",
    "updateDate": "2026-01-15T21:47:35.107250Z",
    "notificationTypes": ["*"],
    "restricted": false
  }
}

CPN requires name and enabled in the request body in addition to the common fields. See the Create Subscription reference for the full schema.

curl --request POST \
  --url https://api.circle.com/v2/cpn/notifications/subscriptions \
  --header "Authorization: Bearer $CIRCLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "endpoint": "https://your-app.example.com/webhooks",
    "name": "CPN Webhooks",
    "enabled": true,
    "notificationTypes": ["*"]
  }'

Example response:

{
  "data": {
    "id": "1609aa1c-510a-448d-b9b9-3a13566ff922",
    "name": "CPN Webhooks",
    "endpoint": "https://your-app.example.com/webhooks",
    "enabled": true,
    "createDate": "2026-01-15T21:47:35.107250Z",
    "updateDate": "2026-01-15T21:47:35.107250Z",
    "notificationTypes": ["*"],
    "restricted": false
  }
}

See the Create Subscription reference for the full schema.

curl --request POST \
  --url https://api.circle.com/v2/stablefx/notifications/subscriptions \
  --header "Authorization: Bearer $CIRCLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "endpoint": "https://your-app.example.com/webhooks",
    "notificationTypes": ["*"]
  }'

Example response:

{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "name": "Transactions Webhook",
    "endpoint": "https://your-app.example.com/webhooks",
    "enabled": true,
    "createDate": "2026-01-15T21:47:35.107250Z",
    "updateDate": "2026-01-15T21:47:35.107250Z",
    "notificationTypes": ["*"],
    "restricted": false
  }
}

Circle Mint subscriptions deliver all account events. Filtering by notificationTypes isn’t supported. See the Create Subscription reference for the full schema.

curl --request POST \
  --url https://api.circle.com/v1/notifications/subscriptions \
  --header "Authorization: Bearer $CIRCLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "endpoint": "https://your-app.example.com/webhooks"
  }'

Example response:

{
  "data": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "endpoint": "https://your-app.example.com/webhooks",
    "subscriptionDetails": [
      {
        "url": "arn:aws:sns:us-east-1:908968368384:fcb4a2c9-9c4f-4706-b312-6b22650f5d17",
        "status": "confirmed"
      }
    ]
  }
}

Gateway uses a permissionless subscription that includes the wallet addresses and blockchain domains to monitor. See the Create Subscription reference for the full schema.

curl --request POST \
  --url https://api.circle.com/v2/notifications/subscriptions/permissionless \
  --header "Authorization: Bearer $CIRCLE_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "environment": "mainnet",
    "endpoint": "https://your-app.example.com/webhooks",
    "addresses": ["0xYourWalletAddress"],
    "domains": [0],
    "notificationTypes": ["gateway.*"]
  }'

Example response:

{
  "data": {
    "id": "9d1fa351-b24d-442a-8aa5-e717db1ed636",
    "name": "Gateway Webhooks",
    "endpoint": "https://your-app.example.com/webhooks",
    "environment": "mainnet",
    "enabled": true,
    "addresses": ["0xYourWalletAddress"],
    "domains": [0],
    "notificationTypes": ["gateway.*"],
    "createDate": "2026-01-15T21:47:35.107250Z",
    "updateDate": "2026-01-15T21:47:35.107250Z"
  }
}