Webhooks and Asynchronous Verification Results: Designing a Reliable KYC Integration Pipeline

Many identity checks don't finish inside a single request. A customer starts onboarding on your website, switches to their phone to photograph a passport, completes a selfie and liveness check, and the result comes back minutes later. AML/PEP screening may run as a separate step. Your backend has to learn the outcome without someone watching a spinner.

That's where webhooks come in. They are also where many KYC integrations quietly break. A missed callback leaves a customer stuck in "pending" forever. A duplicate callback triggers two account activations. A spoofed callback approves someone who was never verified.

This post covers how to design the receiving side so it holds up in production.

Why Verification Results Arrive Asynchronously

A synchronous API call works well when you already have the document images in hand. You send them, and you get back OCR data, document authentication results and a face match score in the response.

Hosted or cross-device flows work differently. A tool like Docupass hands the capture experience to the end user. Your server creates a verification session, the user completes it on their own time and device, and the platform notifies you when it's done. Your system can't predict when that will happen, or whether it will happen at all.

The integration therefore has two halves:

• Starting a verification. This is easy.
• Reliably reacting to its outcome. This is the hard part.

Principle 1: Treat the Webhook as a Signal, Not the Source of Truth

The safest pattern is to treat an incoming webhook as a notification that something changed. Your server then confirms the result through an authenticated API request before acting on it.

This gives you three properties at once:

• Forgery resistance. A forged request can at worst prompt you to look something up. It cannot approve anyone.
• Fresh data. You always act on the latest authoritative state, not whatever was in a payload that may have been delayed.
• Simpler handling. Lookup and processing logic can be shared between webhooks and any polling or reconciliation jobs.

If you do act directly on payload contents, validate them strictly. Only accept HTTPS. Check any shared secret or signature mechanism your provider offers. Reject payloads that reference sessions your system never created.

Principle 2: Acknowledge Fast, Process Later

Webhook senders generally expect a quick success response. If your endpoint runs the whole decision process inline, a slow call can cause a timeout and a retry while the first attempt is still running. Examples include a sanctions re-check, a database write or a CRM update.

Split the endpoint into two steps:

1. Validate the request, persist the raw event, and enqueue a job.
2. Return a success status immediately.

A background worker then handles the real work: fetching the authoritative result, updating the customer record and triggering downstream actions. If the worker fails, the event is still safely stored and can be retried on your terms.

Principle 3: Design for Duplicates and Disorder

Assume every webhook can arrive more than once, and that events for the same session can arrive out of order.

Idempotency

Record a unique identifier for each processed event or session transition. Before acting, check whether that work has already been done. Account activation, welcome emails and limit increases should all be idempotent. Running them twice should produce the same outcome as running them once.

A Verification State Machine

Model each verification as a set of explicit states with allowed transitions. For example:

• Created: session issued, user not yet started
• In progress: user has begun capture
• Completed – pending review: automated checks finished, manual review required
• Approved or Rejected: terminal states
• Expired: user never finished

When an event arrives, apply it only if it represents a valid forward transition. A late "in progress" event should never overwrite "approved." This one rule removes a whole class of race conditions.

Principle 4: Plan for Webhooks That Never Arrive

Networks fail, endpoints get misconfigured during deployments, and certificates expire. A reliable pipeline does not depend on every callback being delivered.

Add a reconciliation job that periodically finds verifications sitting in non-terminal states longer than expected. For each one, query the API directly for the current status. Sessions the user abandoned should move to "expired" after a timeout you define. That timeout can then trigger a reminder email or a fallback path.

Also alert on your own endpoint's health. A sudden drop in received webhooks is often the first sign of a broken deployment, long before customers complain.

Principle 5: Store Only What You Need

Verification results can contain extracted document fields, face images and screening matches. Your webhook handler is not the place to dump everything into a general-purpose database or log file.

Decide up front which fields your business actually needs:

• Decision data: the outcome, the document type and country, the key extracted fields required for your records, and any review notes.
• Raw logs: request logs should record event IDs and status codes, not personal data or images.

Keep sensitive artifacts in storage designed for them, with access controls and retention rules that match your regulatory obligations.

Building an Audit Trail Compliance Will Trust

Compliance teams will eventually ask why a specific customer was approved and when. Your event store can answer that if you design it to. For each verification, record:

• each received event and when it arrived
• when your system fetched the authoritative result
• which state transition was applied, and by what (automation or a named reviewer)

This timeline is also invaluable for debugging. "The customer says they finished but we show pending" becomes a quick lookup instead of an investigation.

Testing Before Production

Don't wait for live traffic to find out how your handler behaves. Before launch, deliberately test these scenarios:

• Duplicate delivery: send the same event twice.
• Out-of-order events: send a late intermediate event after a terminal one.
• Downtime: take your endpoint offline, confirm reconciliation recovers the missed results, then bring it back.
• Forged requests: send a request with an invalid secret or an unknown session ID and confirm it is rejected.
• Abandonment: let a session expire without completion.

A Quick Checklist

• HTTPS-only endpoint with request authentication
• Fast acknowledgement, background processing
• Authoritative result fetched via API before decisions
• Idempotent side effects
• Explicit state machine with forward-only transitions
• Reconciliation job and expiry timeouts
• Minimal data retention and an event-level audit trail

Get these right and asynchronous verification stops being a source of support tickets. It becomes a dependable part of your onboarding flow.