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

Authorizations

​
Authorization
string
header
required

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

Headers

​
X-Request-Id
string

Developer-provided parameter used to identify this request. Useful when communicating with Circle Support. 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.

​
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"

​
notificationTypes
enum<string>[]

The notification types to subscribe to. If not provided, the webhook will be unrestricted, and a notification is sent for every notification type. If the wildcard (*) or any combination of the wildcard and a set of notification types is provided, the webhook will also be unrestricted. If a set of notification types are provided, the webhook will be restricted. The restricted status of the webhook is returned in the response object. Each category of notification types also has a wildcard, which will restrict to all notification types from that category.

Available options:
*,
transactions.*,
transactions.inbound,
transactions.outbound,
challenges.*,
challenges.accelerateTransaction,
challenges.cancelTransaction,
challenges.changePin,
challenges.contractExecution,
challenges.createTransaction,
challenges.createWallet,
challenges.initialize,
challenges.restorePin,
challenges.setPin,
challenges.setSecurityQuestions,
contracts.*,
contracts.eventLog,
modularWallet.*,
modularWallet.userOperation,
modularWallet.inboundTransfer,
modularWallet.outboundTransfer,
travelRule.*,
travelRule.statusUpdate,
travelRule.deny,
travelRule.approve,
rampSession.*,
rampSession.completed,
rampSession.depositReceived,
rampSession.expired,
rampSession.failed,
rampSession.kycApproved,
rampSession.kycRejected,
rampSession.kycSubmitted
Example:
["*"]

Response

Successfully created a notification subscription.

​
data
Subscription · object

Contains information about a webhook notification subscription.