Skip to main content
Circle uses webhooks to notify your application when events occur. Because many operations across Circle products complete asynchronously, your application doesn’t block on the result of an API call. Instead, Circle sends an HTTP POST request to an endpoint you configure when the state of a resource changes, so your application can react to the event.

​
Event model

Each webhook notification is an HTTP POST request to a subscriber endpoint you configure. Every notification includes:
  • Subscription ID: Identifies the subscription that produced the notification. Use it to route events to the correct handler.
  • Notification ID: Uniquely identifies the notification. The same ID is reused if Circle retries delivery, so use it to deduplicate.
  • Event type: Indicates the kind of state change that occurred (for example, a transaction confirmed, a payment failed).
  • Payload: The resource that changed, including its current state.
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.

​
Delivery 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, and Circle reuses the same notification ID across retries. Your endpoint must be idempotent: processing the same notification ID more than once must not cause incorrect state in your application. Deduplicate on the notification ID before applying side effects.
To inspect delivery attempts, view payloads, or resend a notification, view Webhook Logs in the Circle Console (Wallets, Contracts) or CPN Console (CPN).