Skip to main content
POST
/
v2
/
notifications
/
subscriptions
/
permissionless
Create a webhook subscription
curl --request POST \
  --url https://api.circle.com/v2/notifications/subscriptions/permissionless \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "environment": "TEST",
  "endpoint": "https://example.org/handler/for/notifications",
  "addresses": [
    "0x1234567890abcdef1234567890abcdef12345678"
  ],
  "domains": [
    "26"
  ],
  "name": "Gateway Webhooks",
  "enabled": true,
  "notificationTypes": [
    "gateway.*"
  ]
}
'
{
  "data": {
    "id": "c4d1da72-111e-4d52-bdbf-2e74a2d803d5",
    "endpoint": "https://example.org/handler/for/notifications",
    "enabled": true,
    "notificationTypes": [
      "gateway.*"
    ],
    "restricted": false,
    "addresses": [
      "0x1234567890abcdef1234567890abcdef12345678"
    ],
    "domains": [
      "26"
    ],
    "environment": "TEST",
    "createDate": "2023-01-01T12:04:05Z",
    "updateDate": "2023-01-01T12:04:05Z",
    "name": "Gateway Webhooks"
  }
}

Documentation Index

Fetch the complete documentation index at: https://developers.circle.com/llms.txt

Use this file to discover all available pages before exploring further.

Authorizations

​
Authorization
string
header
required

Circle's API Keys are formatted in the following structure "PREFIX:ID:SECRET". All three parts are required to make a successful request.

Headers

​
X-Request-Id
string<uuid>

Developer-provided identifier for this request, used for tracing requests in Wallets API logs and the Developer Console, and when communicating with Circle Support. Must be a UUID to appear in logs. Non-UUID values are accepted by the API but are ignored by logging and tracing systems.

A unique identifier, which can be helpful for identifying a request when communicating with Circle support.

Example:

"2adba88e-9d63-44bc-b975-9b6ae3440dde"

Body

application/json

Schema for the request payload to create a new subscription.

Required parameters to create a new subscription.

​
environment
enum<string>
required

The environment for the subscription. Use TEST to receive testnet events or LIVE to receive mainnet events.

Available options:
TEST,
LIVE
Example:

"TEST"

​
endpoint
string
required

URL of the endpoint to subscribe to notifications. Must be publicly accessible, use HTTPS, and respond with a 2XX status to a POST request.

Example:

"https://example.org/handler/for/notifications"

​
addresses
string[]
required

The EVM or Solana wallet addresses to monitor. Notifications fire only for events on these addresses.

Example:
[
  "0x1234567890abcdef1234567890abcdef12345678"
]
​
domains
string[]
required

The CCTP domain identifiers for the blockchains to watch.

Example:
["26"]
​
name
string

Name of the webhook notification subscription.

Example:

"Gateway Webhooks"

​
enabled
boolean
default:true

Whether the subscription is enabled. Defaults to true.

Example:

true

​
notificationTypes
enum<string>[]

The notification types to subscribe to. If omitted or if gateway.* is provided, the webhook is unrestricted for Gateway events and the response returns restricted: false. If individual event types are provided, the webhook is restricted to those event types.

Notification type for Gateway webhook subscriptions. Omit notificationTypes or use gateway.* to subscribe to all current and future Gateway notification types. Use individual event types to restrict delivery to specific Gateway events.

Available options:
gateway.*,
gateway.deposit.finalized,
gateway.mint.finalized,
gateway.mint.forwarded
Example:
["gateway.*"]

Response

Successfully created a webhook subscription.

​
data
PermissionlessSubscription · object

Contains information about a permissionless webhook notification subscription.