Track a Plaid Identity Verification session's progress using STEP_UPDATED, STATUS_UPDATED, and RETRIED webhook codes
domain: plaid.com · 5 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
In-depth guide
Plaid webhook verification — the full failure-mode walkthrough related to plaid.com, checked against official docs, with linked verified routes.
Steps
Configure the IDV webhook URL in the Plaid Dashboard, since it cannot be set via /link/token/create
Handle STEP_UPDATED events to track progress as the user completes individual steps (e.g. document, selfie) within the session
Handle STATUS_UPDATED events to detect overall session status transitions such as completion or failure
Handle RETRIED events when a user restarts a failed or expired session, and reconcile it against the original identity_verification_id
Do not assume delivery order across webhook codes — reconcile state by fetching /identity_verification/get rather than trusting event sequence alone
Known gotchas
Plaid does not guarantee webhook delivery order, so a STATUS_UPDATED completion event could theoretically be processed before a preceding STEP_UPDATED event
The webhook URL is dashboard-configured per project, not passed at token creation, so per-session webhook overrides aren't supported this way
RETRIED sessions reuse identifiers tied to the same client_user_id, so failing to reconcile against the prior identity_verification_id can create duplicate case records
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?