Webhooks - Circle Docs

Circle uses webhooks to notify your application when events occur. Circle products handle many operations in the background. When a resource changes state, Circle sends an HTTP POST to the endpoint you configure so your application can react.

Notification API versions

Circle offers two notification systems: v2 and v1 (legacy). V2 now supports all Circle products. See Set up a webhook endpoint for the flow that matches your product, or learn how to migrate your existing endpoints to v2.

Event model

Each webhook notification is an HTTP POST request to a subscriber endpoint you configure. The envelope shape depends on the notification API version.

v2 notifications
v1 notifications

Used by Circle Wallets, Circle Contracts, CPN payments, CPN Managed Payments, Circle Mint, Digital Asset Accounts, End User Onboarding, Gateway, and StableFX. Each notification includes:

Field	Type	Description
`subscriptionId`	string (UUIDv4)	Identifies the subscription that produced the notification. Use it to route events to the correct handler.
`notificationId`	string (UUIDv4)	Uniquely identifies the notification. The same ID is reused if Circle retries delivery, so use it to deduplicate.
`notificationType`	string	The event type (for example, `transactions.inbound`, `cpn.payment.completed`).
`notification`	object	The resource that changed, including its current state. The shape matches the corresponding API endpoint’s response object.
`timestamp`	string	ISO 8601 timestamp of the event.
`version`	number	Schema version. Always `2`.

You subscribe to the events your application cares about. When a corresponding state change occurs in Circle’s systems, Circle sends a notification to your endpoint.

Webhooks v1 are legacy and being phased out. If you have existing integrations with v1 endpoints, learn how to migrate to v2.

v1 uses Amazon Simple Notification Service (SNS) as the delivery layer, so each notification arrives as an SNS message wrapping the Circle event payload.The outer SNS envelope includes:

Field	Type	Description
`Type`	string	The SNS message type. `Notification` for events, `SubscriptionConfirmation` for the one-time handshake described below.
`MessageId`	string	Unique identifier for this delivery. Reused if SNS retries, so use it to deduplicate.
`TopicArn`	string	The SNS topic the subscription is bound to.
`Message`	string	The Circle event payload, encoded as a JSON string. Parse it to access the inner envelope described next.
`Signature`	string	Base64-encoded signature of the canonical message string.
`SigningCertURL`	string	URL of the public certificate used to verify `Signature`. See Verify webhook signatures.

The inner Circle envelope, parsed from Message, includes:

Field	Type	Description
`clientId`	string (UUIDv4)	Identifies the Circle account that owns the resource.
`notificationType`	string	The event topic (for example, `deposits`, `transfers`). The topic determines which resource key is present on the envelope.
`version`	number	Schema version for the notification payload.
`customAttributes`	object	Echoes selected envelope attributes such as `clientId`.
`<resourceKey>`	object	The topic-specific resource (for example, `deposit`, `transfer`, `payout`) carrying the current state of the changed object.

When you register a v1 subscription, your endpoint first receives a one-time SubscriptionConfirmation message containing a SubscribeURL. Visit that URL to complete the handshake before events begin flowing. See Set up a webhook endpoint for the full flow.

Delivery, ordering, and idempotency

Circle delivers webhook notifications at least once. If your endpoint does not respond with a success status, or if the request fails, Circle retries delivery. The same notification can be sent more than once. Keep in mind the following:

Your endpoint must be idempotent: Your handler must produce the same result each time it runs. Deduplicate on the Notification ID (v2) or MessageId (v1) before applying side effects.
Your application must not assume delivery order: Notifications for successive state changes (for example, CONFIRMED then COMPLETE) can arrive in a different order than when the state changes occurred. Handle each notification based on the state it carries, not on its arrival sequence.

To inspect delivery attempts, view payloads, or resend a notification, view Webhook Logs in the Circle Console (Wallets, Contracts) or CPN Console (CPN).

​Notification API versions

​Event model

​Delivery, ordering, and idempotency

Notification API versions

Event model

Delivery, ordering, and idempotency