Skip to main content
POST
/
v2
/
cpn
/
notifications
/
subscriptions
Create a webhook subscription
curl --request POST \
  --url https://api.circle.com/v2/cpn/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.

The type of notification that can be subscribed to. Supports wildcard patterns (e.g., 'cpn.payment.') to subscribe to all notifications within a category. The '' wildcard can be used to subscribe to all notifications.

Available options:
*,
cpn.payment.*,
cpn.payment.cryptoFundsPending,
cpn.payment.fiatPaymentInitiated,
cpn.payment.completed,
cpn.payment.failed,
cpn.payment.delayed,
cpn.rfi.*,
cpn.rfi.informationRequired,
cpn.rfi.inReview,
cpn.rfi.approved,
cpn.rfi.rejected,
cpn.transaction.*,
cpn.transaction.broadcasted,
cpn.transaction.completed,
cpn.transaction.failed
Example:
["*"]

Response

Successfully created a webhook subscription.

​
data
Subscription · object

Contains information about a webhook notification subscription.