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

# Customer onboarding webhooks

> Receive customer onboarding lifecycle updates for fiat withdrawals, deposits, and virtual accounts. These events describe onboarding cases, not payments or settled funds.

Receive customer onboarding lifecycle updates for fiat withdrawals, deposits, and virtual accounts. These events describe onboarding cases, not payments or settled funds.

## Delivery and signature

Configure webhook URLs on the business master API key for the customer network (mainnet or testnet). Delivery uses active URLs, falling back to the legacy single URL when no active URLs exist. These are business-level events: no wallet is required. Verify the HMAC-SHA512 signature using that master API key, not a wallet key. The default header is x-blockradar-signature; configured signature-header overrides still apply.

## Events

| Event | Meaning |
| - | - |
| `customer.onboarding.submitted` | Submitted to the provider. |
| `customer.onboarding.in_review` | Under review. |
| `customer.onboarding.action_required` | More customer action is required. Fetch the latest case and its current requirements. |
| `customer.onboarding.approved` | Approved; retry the intended operation with a fresh session. |
| `customer.onboarding.rejected` | Rejected. |
| `customer.onboarding.failed` | Onboarding processing failed. |
| `customer.onboarding.expired` | Onboarding expired. |

## Payload

```json theme={null}
{
  "event": "customer.onboarding.approved",
  "data": {
    "id": "8392013d-2481-47c9-b5e3-b61b22b8ff82",
    "customerId": "18d2f159-e0cd-4a45-b735-e9dfe0f7520a",
    "provider": {
      "id": "1128dd40-2c94-4c16-a6bf-fbbc6afee52c",
      "slug": "noah",
      "name": "Noah"
    },
    "status": "approved",
    "previousStatus": "in_review",
    "reason": null,
    "availableActions": [],
    "createdAt": "2026-10-31T10:00:00.000Z",
    "updatedAt": "2026-10-31T10:15:00.000Z"
  }
}
```

## Fields

| Field | Meaning |
| - | - |
| `data.id` | Onboarding case ID; not a customer or transaction ID. |
| `data.customerId` | Customer ID. |
| `data.provider` | Provider ID, slug and display name. |
| `data.status` | Current onboarding status. |
| `data.previousStatus` | Previous status, or null when unavailable. |
| `data.reason` | Reason, or null. |
| `data.availableActions` | Available actions: edit\_and\_resubmit and/or refresh\_provider\_steps, or an empty array. Fetch the case before acting. |
| `data.createdAt` | Case creation timestamp. |
| `data.updatedAt` | Case update timestamp; not webhook delivery time. |

## Handling updates

Acknowledge promptly with HTTP 200 and process idempotently. Retries can deliver duplicates; use the case ID, event and updatedAt to recognize repeated updates and fetch the latest case before changing state. Repeated identical status/reason updates are suppressed; action\_required can be emitted again when actions or hosted sessions change. Not every intermediate status has an event. Approval does not move funds or guarantee that the business integration is eligible.

## See also

[Customer fiat flows](https://docs.blockradar.co/en/guides/customer-fiat-flows.md) · [Delivery and signature](https://docs.blockradar.co/en/utilities/webhooks.md)

[Refresh onboarding](https://docs.blockradar.co/en/api-reference/customer-onboarding/refresh-request.md) — Request new withdrawal rates or a new deposit quote to create a fresh fiat session. Do not reuse a session created before approval. Customer onboarding state changes can also emit customer.onboarding.\* webhooks; a refresh does not guarantee a new event for an unchanged case.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.