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
- Configure webhook delivery in Set Webhook Notification Info.
- Consume onboarding events through
USER_ONBOARDING_UPDATE. - Verify webhook authenticity with
md-webhook-signature(HMAC validation — see Webhooks). - 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
| Status | Meaning |
|---|---|
ONBOARDING | User still has required onboarding tasks pending |
ACTIVE | User completed required onboarding tasks and can operate |
INACTIVE | User is not currently enabled for operations |
When does the status change?
ONBOARDINGis 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.ACTIVEis set automatically once all required onboarding tasks are completed and validated for the user's country. This is the next status you will see afterONBOARDING.INACTIVEis set if the user is later disabled or blocked.INACTIVEis also set when anACTIVEindividual is later flagged as PEP. The user returns toACTIVEautomatically 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_UPDATEmay exist in legacy integrations, but for onboarding progression the preferred event isUSER_ONBOARDING_UPDATE.
Related pages
Updated 13 days ago