> ## 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.

> ## Agent Instructions
> Before reading these docs, install the relevant Circle Skill to get pre-loaded context — skills are LLM-optimized and cover architecture decisions, correct flows, and common pitfalls. In Claude Code: run /plugin marketplace add circlefin/skills then /plugin install circle-skills@circle. With Vercel Skills CLI: run npx skills add circlefin/skills. Available skills: use-usdc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-usdc/SKILL.md (balances, transfers, approvals on EVM and Solana); EURC has no skill — see https://developers.circle.com/stablecoins/what-is-eurc.md; bridge-stablecoin https://github.com/circlefin/skills/blob/master/plugins/circle/skills/bridge-stablecoin/SKILL.md (crosschain transfers via CCTP, USDC, EURC, and third-party assets); use-arc https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-arc/SKILL.md (Arc chain config, contract deployment, USDC bridging — Arc docs: https://docs.arc.io/llms.txt); use-circle-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-circle-wallets/SKILL.md (choose wallet type); use-developer-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-developer-controlled-wallets/SKILL.md (custodial wallets for payouts and treasury); use-user-controlled-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-user-controlled-wallets/SKILL.md (embedded wallets with Web2 login); use-modular-wallets https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-modular-wallets/SKILL.md (smart contract wallets with passkeys and ERC-4337); use-gateway https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-gateway/SKILL.md (unified USDC balance, nanopayments); use-smart-contract-platform https://github.com/circlefin/skills/blob/master/plugins/circle/skills/use-smart-contract-platform/SKILL.md (deploy, interact, monitor contracts). Pair any skill with the Circle MCP server for live SDK signatures, contract addresses, and chain IDs: {"mcpServers":{"circle":{"url":"https://api.circle.com/v1/codegen/mcp"}}}.
> Read the product overview first. Each product has an overview explaining when and why to use it. Read it before quickstarts.
> Pick the right wallet type. Developer-controlled (you hold keys), user-controlled (end user holds keys via PIN/social login), or modular (smart contract wallets with passkeys). See https://developers.circle.com/wallets.md.
> Use CCTP V2 for crosschain transfers. CCTP natively transfers USDC and EURC via burn-and-mint, and supports permissionless wrapping of third-party assets via lock-and-mint. V1 is legacy; always use V2 unless V1 is specified or the chain requires it (Noble, Sui, and Aptos still require V1). Migration guide: https://developers.circle.com/cctp/migration-from-v1-to-v2.md.
> Use Bridge Kit for frontend bridging. Wraps CCTP with a simpler SDK for user-facing apps. Use CCTP directly for backend transfers.
> Gas Station vs Paymaster. Gas Station sponsors gas for Circle Wallet transactions. Paymaster lets users pay gas in USDC. Different use cases — read both overviews.
> Gateway Nanopayments for sub-cent payments. Gasless USDC micropayments down to $0.000001 via x402 and batched settlement. For pay-per-request APIs, AI agent payments, streaming.
> Look up USDC addresses per chain. Never hardcode — use https://developers.circle.com/stablecoins/usdc-contract-addresses.md.
> Prefer SDKs over raw API calls. Node.js and Python SDKs handle auth, retries, and errors.
> API key required. Bearer token in Authorization header. Testnet and mainnet use separate keys and may use different base URLs depending on the product.
> Set up webhooks when available. Most operations are async. Webhooks deliver transaction confirmations and state changes.
> When calling list endpoints, paginate using pageSize and pageAfter until no nextPageAfter cursor is returned—stopping at the first page silently misses records.
> Building an AI agent? Start with the Agent Stack—Circle CLI, agent wallets, and nanopayments built for autonomous use cases: https://developers.circle.com/agent-stack.md.

# Webhook notifications

> Reference for End User Onboarding webhook event types with example payloads.

End User Onboarding delivers asynchronous application lifecycle events as
webhook notifications so you can drive your integration with real-time updates
instead of polling
[`GET /v1/onboarding/partner/applications/{id}`](/api-reference/end-user-onboarding/get-application).

Notifications are delivered as Amazon SNS messages on the
[v1 notification system](/api-reference/webhooks#notification-api-versions). To
register a webhook endpoint, create a subscription for End User Onboarding
notifications in the [CPN Console](https://console.circle.com) under
**Developer > Subscriptions**, then see
[Set up a webhook endpoint](/api-reference/webhook-endpoints#v1-notifications).

## When notifications fire

Webhooks are sent only for **asynchronous** outcomes that you cannot observe
from the response to your own API call. Synchronous transitions you trigger
directly—such as `DRAFT` → `SUBMITTED` from a submit request—are not delivered
as webhooks because the result is already in the HTTP response.

| Notification type | Fires when the application transitions to | From |
| - | - | - |
| `onboarding_application_rfi_requested` | `PENDING_CUSTOMER_INFORMATION` | `IN_REVIEW` |
| `onboarding_application_approved` | `APPROVED` | `IN_REVIEW` |
| `onboarding_application_denied` | `DENIED` | `IN_REVIEW` |
| `onboarding_application_cancelled` | `CANCELLED` | `DRAFT` or `IN_REVIEW` |
| `onboarding_periodic_review_requested` | `DRAFT` | `IN_REVIEW` |

`onboarding_application_rfi_requested` signals that the compliance team has
issued one or more Requests for Information (RFIs). See
[Handle requests for information](/cpn/managed-payments/end-user-onboarding/howtos/handle-rfis)
for the RFI workflow, and
[Application types and states](/cpn/managed-payments/end-user-onboarding/references/application-states)
for the full lifecycle.

## Payload

Every End User Onboarding notification carries the same flat payload.

| Field | Type | Description |
| - | - | - |
| `clientId` | UUID | Identifier of the partner the application belongs to. Used to route the notification to your endpoint. |
| `notificationType` | string | The event type, for example `onboarding_application_rfi_requested`. |
| `version` | number | Notification system version. Always `1`. |
| `applicationId` | UUID | Identifier of the affected onboarding application. |
| `status` | string | The application's new status. |
| `previousStatus` | string | The application's status immediately before this transition. |

<Note>
  `status` and `previousStatus` use the same values as
  [Application types and states](/cpn/managed-payments/end-user-onboarding/references/application-states).
  Internal review sub-states are collapsed to `IN_REVIEW`, so a transition out of
  review reports `previousStatus` as `IN_REVIEW`.
</Note>

## Event types

### `onboarding_application_rfi_requested`

The compliance team issued one or more RFIs and the application moved to
`PENDING_CUSTOMER_INFORMATION`. Fetch the open RFIs with
[List RFIs](/api-reference/end-user-onboarding/list-rfis) (the application's
`pendingRfis` array also carries the bundle IDs), respond to each, then
resubmit.

<Accordion title="Example payload">
  ```json theme={null}
  {
    "clientId": "880e8400-e29b-41d4-a716-446655440099",
    "notificationType": "onboarding_application_rfi_requested",
    "version": 1,
    "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
    "status": "PENDING_CUSTOMER_INFORMATION",
    "previousStatus": "IN_REVIEW"
  }
  ```
</Accordion>

### `onboarding_application_approved`

Compliance review completed and the application was approved. This is a terminal
state.

<Accordion title="Example payload">
  ```json theme={null}
  {
    "clientId": "880e8400-e29b-41d4-a716-446655440099",
    "notificationType": "onboarding_application_approved",
    "version": 1,
    "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
    "status": "APPROVED",
    "previousStatus": "IN_REVIEW"
  }
  ```
</Accordion>

### `onboarding_application_denied`

Compliance review completed and the application was denied. This is a terminal
state.

<Accordion title="Example payload">
  ```json theme={null}
  {
    "clientId": "880e8400-e29b-41d4-a716-446655440099",
    "notificationType": "onboarding_application_denied",
    "version": 1,
    "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
    "status": "DENIED",
    "previousStatus": "IN_REVIEW"
  }
  ```
</Accordion>

### `onboarding_application_cancelled`

The application was canceled. `previousStatus` reflects the application's status
before cancellation and depends on the application type. This is a terminal
state.

<Accordion title="Example payload">
  ```json theme={null}
  {
    "clientId": "880e8400-e29b-41d4-a716-446655440099",
    "notificationType": "onboarding_application_cancelled",
    "version": 1,
    "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
    "status": "CANCELLED",
    "previousStatus": "DRAFT"
  }
  ```
</Accordion>

### `onboarding_periodic_review_requested`

A periodic review application moved from `IN_REVIEW` back to `DRAFT`, making it
editable. Use this notification to start the partner response flow for the
review request.

<Accordion title="Example payload">
  ```json theme={null}
  {
    "clientId": "880e8400-e29b-41d4-a716-446655440099",
    "notificationType": "onboarding_periodic_review_requested",
    "version": 1,
    "applicationId": "6bb28d72-8a8e-4afc-9086-66f89af954eb",
    "status": "DRAFT",
    "previousStatus": "IN_REVIEW"
  }
  ```
</Accordion>

## See also

* [Application types and states](/cpn/managed-payments/end-user-onboarding/references/application-states)
* [Submit and track applications](/cpn/managed-payments/end-user-onboarding/howtos/submit-and-track-applications)
* [Handle requests for information](/cpn/managed-payments/end-user-onboarding/howtos/handle-rfis)