Webhook events

Stablecoin Payins and Stablecoin Payouts emit webhook events so your server can react to deposit-address assignment, settled payments, recipient review outcomes, and payout status changes. Subscribe to these events instead of polling for status.

Subscription endpoint: POST /v1/notifications/subscriptions
Setup: Circle APIs notifications quickstart

All payloads use the following envelope structure.

Envelope field	Type	Description
`clientId`	string	Your Circle client identifier.
`notificationType`	string	Event type identifier. See Event types.
`version`	number	Schema version. Always `1`.
`<resourceKey>`	object	Event-specific data. The key name varies by event type.

Event types

`notificationType`	Resource key	Trigger
`paymentIntents`	`paymentIntent`	Intent created, deposit address assigned, or (transient intents) intent completed.
`payments`	`payment`	A payin settles, or a refund changes status. Discriminated by `type`.
`addressBookRecipients`	`addressBookRecipient`	Recipient status changes, such as `pending` to `active`.
`payouts`	`payout`	Payout status changes, such as `pending`, `complete`, or `failed`.

Payment intent events

The paymentIntents notification fires when you create an intent, when Circle assigns the deposit address, and—for transient intents—when the intent reaches complete. Continuous intents stay at active and never advance to complete; reconcile their transfers through the payments event instead. Status values observed in timeline[].status: created, pending, active, complete.

Example paymentIntents payload

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "paymentIntents",
  "version": 1,
  "paymentIntent": {
    "id": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "type": "continuous",
    "currency": "USD",
    "settlementCurrency": "USD",
    "amountPaid": { "amount": "0.00", "currency": "USD" },
    "paymentMethods": [
      {
        "type": "blockchain",
        "chain": "BASE",
        "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
      }
    ],
    "timeline": [
      { "status": "pending", "time": "2026-04-12T20:13:38.188286Z" },
      { "status": "created", "time": "2026-04-12T20:13:35.579331Z" }
    ]
  }
}

Payment events

The payments notification fires whenever an inbound transfer settles or a refund changes status. Payments and refunds share this channel and are discriminated by the type field (payment or refund). The payload links back to its intent through paymentIntentId. Status values: pending, paid.

Example payments payload

{
  "clientId": "5b057f1e-743c-4aeb-beeb-ef7b2e16f291",
  "notificationType": "payments",
  "version": 1,
  "payment": {
    "id": "66c56b6a-fc79-338b-8b94-aacc4f0f18de",
    "type": "payment",
    "status": "paid",
    "amount": { "amount": "1.00", "currency": "USD" },
    "paymentIntentId": "e2e90ba3-9d1f-490d-9460-24ac6eb55a1b",
    "fromAddresses": {
      "chain": "BASE",
      "addresses": ["0x0d4344cff68f72a5b9abded37ca5862941a62050"]
    },
    "depositAddress": {
      "chain": "BASE",
      "address": "0x97de855690955e0da79ce5c1b6804847e7070c7f"
    },
    "transactionHash": "0x7351585460bd657f320b9afa02a52c26d89272d0d10cc29913eb8b28e64fd906"
  }
}

Address book recipient events

The addressBookRecipients notification fires when a recipient’s status changes, such as when review completes and the recipient becomes active. Wait for active before you send a payout to the recipient. Status values: pending, inactive, active, denied.

Example addressBookRecipients payload

{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "addressBookRecipients",
  "version": 1,
  "addressBookRecipient": {
    "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe1",
    "chain": "BASE",
    "address": "0x65bfcf1a6289a0b77b4d3f7d12005a05949fd8c3",
    "status": "active",
    "createDate": "2026-05-01T14:16:34.985353Z",
    "updateDate": "2026-05-01T14:18:02.123456Z"
  }
}

Payout events

The payouts notification fires when a payout status changes. The payload includes the resolved fees and onchain networkFees. Status values: pending, complete, failed.

Example payouts payload

{
  "clientId": "a03a47ff-b0eb-4070-b3df-dc66752cc802",
  "notificationType": "payouts",
  "version": 1,
  "payout": {
    "id": "b8627ae8-732b-4d25-b947-1df8f4007a29",
    "sourceWalletId": "12345",
    "destination": {
      "type": "address_book",
      "id": "dff5fcb3-2e52-5c13-8a66-a5be9c7ecbe1"
    },
    "amount": { "amount": "3000.14", "currency": "USD" },
    "toAmount": { "amount": "3000.14", "currency": "USD" },
    "fees": { "amount": "0.00", "currency": "USD" },
    "networkFees": { "amount": "0.30", "currency": "USD" },
    "status": "complete",
    "createDate": "2026-05-01T14:20:30.000Z",
    "updateDate": "2026-05-01T14:21:12.000Z"
  }
}

Fiat payouts

Managed Payments

Stablecoin payments

Event types

Payment intent events

Payment events

Address book recipient events

Payout events

​Event types

​Payment intent events

​Payment events

​Address book recipient events

​Payout events

Event types

Payment intent events

Payment events

Address book recipient events

Payout events