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

{
  "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 · Delivery and signature

Refresh onboarding — 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.