Onboarding status and webhook

Use webhook-first tracking for onboarding lifecycle.

For onboarding state changes, the recommended event is USER_ONBOARDING_UPDATE.


Payload contract

For the full USER_ONBOARDING_UPDATE webhook payload — including field descriptions, task names, and a JSON example — see Webhooks → USER_ONBOARDING_UPDATE.


Recommended tracking model

  1. Configure webhook delivery in Set Webhook Notification Info.
  2. Consume onboarding events through USER_ONBOARDING_UPDATE.
  3. Verify webhook authenticity with md-webhook-signature (HMAC validation — see Webhooks).
  4. Keep a query fallback path for recovery scenarios.

Fallback and recovery

If your webhook consumer is temporarily unavailable, use API reads to reconcile state:

This lets you recover final onboarding state and pending requirements without blocking operations.


Status interpretation

StatusMeaning
ONBOARDINGUser still has required onboarding tasks pending
ACTIVEUser completed required onboarding tasks and can operate
INACTIVEUser is not currently enabled for operations

When does the status change?

  • ONBOARDING is the user's initial status, assigned the moment the user is created — at the very start of the onboarding flow. It is set before the user opens the KYC webview or fills in / submits any personal data. Starting or submitting the KYC flow does not change the status by itself.
  • ACTIVE is set automatically once all required onboarding tasks are completed and validated for the user's country. This is the next status you will see after ONBOARDING.
  • INACTIVE is set if the user is later disabled or blocked.
  • INACTIVE is also set when an ACTIVE individual is later flagged as PEP. The user returns to ACTIVE automatically once the PEP documentation is approved — see PEP & FEP Documentation.

When the last required task completes, the change to ACTIVE is delivered as its own USER_ONBOARDING_UPDATE, sent shortly after that task's update, with the new data.user.status and data.updatedTasks: []. A later change to INACTIVE may arrive with updated tasks listed, or without any USER_ONBOARDING_UPDATE. USER_CRIPTO_STATUS_UPDATE / USER_WALLET_STATUS_UPDATE are sent for these status changes, so use them to track ACTIVE and INACTIVE reliably.

The user status moves ONBOARDING → ACTIVE (or → INACTIVE), and back from INACTIVE to ACTIVE in the PEP case above. To track the user filling out and submitting their data and individual KYC tasks progressing, use the per-task fields delivered in USER_ONBOARDING_UPDATE (data.updatedTasks and each task's status) — the top-level status does not change on data submission, only when every required task is completed.


USER_STATUS_UPDATE may exist in legacy integrations, but for onboarding progression the preferred event is USER_ONBOARDING_UPDATE.


Related pages


Did this page help you?