> ## Documentation Index
> Fetch the complete documentation index at: https://developers.circle.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhook events

> Reference for Stablecoin Payins and Stablecoin Payouts webhook event types, payloads, and the notification subscription system.

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](/circle-mint/references/webhook-notifications)

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](#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`.

```json Example paymentIntents payload theme={null}
{
  "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`.

```json Example payments payload theme={null}
{
  "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`.

```json Example addressBookRecipients payload theme={null}
{
  "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`.

```json Example payouts payload theme={null}
{
  "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"
  }
}
```