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

> Reference for Partner Onboarding webhook event types with example payloads.

Partner 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/partner-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 partner onboarding
notifications in the [Circle Mint 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`     |

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

## Payload

Every partner 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 states](/partner-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/partner-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 cancelled. Cancellation is only reachable from `DRAFT`, so
`previousStatus` is always `DRAFT`. 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>

## See also

* [Application states](/partner-onboarding/references/application-states)
* [Submit and track applications](/partner-onboarding/howtos/submit-and-track-applications)
* [Handle requests for information](/partner-onboarding/howtos/handle-rfis)