Skip to main content
Circle Wallets uses webhooks to notify your application when wallet-related events occur. Because blockchain state changes asynchronously, Circle does not block your API calls until finality. Instead, Circle sends event notifications to an endpoint you provide so you can react to state transitions (for example, a deposit confirmed, a transaction failed). This page describes the event model, how delivery and retries work, and how state is communicated. For setup and debugging, see Set Up Webhooks and Troubleshoot webhooks. For event types and payloads, see Webhook events and payloads.

​
Event model

Webhook notifications are HTTP POST requests sent to a subscriber endpoint you configure. Each notification includes:
  • Subscription and notification identifiers—Use them to correlate events and detect duplicates (the same notification can be retried).
  • Event type—For example, transactions.inbound, so you know what kind of state change occurred.
  • Payload—The resource that changed (for example, transaction object with status, amounts, addresses).
You subscribe to the events you care about (for example, inbound transactions, outbound transactions). When the corresponding state change occurs in Circle’s systems (after blockchain confirmation or failure), Circle sends a notification to your endpoint.

​
Asynchronous processing

Transaction lifecycle is asynchronous: you submit a transaction, and later the blockchain confirms or rejects it. Circle tracks state and sends you notifications when it changes. Your app can use these events to update balances, show history, trigger business logic, or alert users. You do not need to poll; you react to the events Circle delivers.

​
Delivery guarantees and retries

Circle attempts to deliver each notification to your endpoint. If your endpoint does not respond with a success status (for example, 2xx) in a defined time, or if the request fails, Circle may retry according to its retry policy. The same notification can be sent more than once (same notification ID); your endpoint should be idempotent so duplicate deliveries do not cause incorrect state. For delivery behavior, retry rules, and how to inspect delivery attempts, see Troubleshoot webhooks.

​
State transitions

Notifications reflect state transitions: for example, a transaction moves from queued to confirmed, or from pending to failed. Each event type corresponds to a transition or a final state. The payload includes the current state of the resource so you can update your systems. For the full list of transaction flow events and payload shapes, see Webhook events and payloads.