Identity verification webhooks connect a KYC or identity proofing provider to the systems that make decisions about an account. This guide explains how to model the event lifecycle, validate and process notifications safely, handle retries and duplicates, monitor integration health, and decide when an implementation needs review.
Overview
A verification API webhook is an HTTP notification sent by a provider when something changes in a verification session, case, document review, biometric check, or related workflow. Your application may use that notification to update a customer record, request additional information, release a product feature, route a case to manual review, or record an audit event.
The webhook should not be treated as a simple “approved” or “rejected” button. A robust integration separates four concerns:
- Authentication: establish that the request came from the expected provider and was not altered.
- Interpretation: map the provider’s event and status to your internal verification state.
- Delivery: process duplicates, delays, out-of-order events, and temporary failures.
- Operations: detect missing notifications, investigate failures, and reconcile your records with the provider.
Event names, payload fields, signature schemes, retry behavior, and API version rules vary by provider. Use this article as a provider-agnostic design checklist, then confirm every detail against the provider’s current documentation and test environment.
Identity verification webhook lifecycle
Customer starts verification
|
v
Provider creates session or case
|
v
Documents, face match, liveness, or review progresses
|
v
Provider emits event --------------> Your endpoint receives request
|
v
Authenticate and validate
|
+-----------------+------------------+
| |
Invalid request Valid request
| |
Reject and log safely Store event or inbox record
|
v
Return timely 2xx response
|
v
Process asynchronously and idempotently
|
v
Update state and trigger next actionA useful design principle is to acknowledge a valid webhook after it has been durably recorded, not only after every downstream action has completed. This limits the chance that a provider retries a legitimate event because your application was waiting on a slow database, queue, notification service, or internal review process. The exact acknowledgment strategy depends on your architecture and the provider’s retry rules.
What to track
1. Event identity and delivery metadata
Build an internal event record that can answer both “what happened?” and “how did we receive it?” Common fields include:
| Field group | Examples to map | Why it matters |
|---|---|---|
| Event identity | Provider event ID, event type, schema or API version | Supports deduplication, routing, and version-aware parsing. |
| Verification reference | Session ID, case ID, applicant ID, customer reference | Connects the event to the correct internal record without relying on a mutable display name. |
| Timing | Provider-created time, provider-updated time, received time, processed time | Shows delivery delay, processing delay, and possible ordering problems. |
| Outcome | Provider status, decision, reason code, review state | Allows explicit mapping to your own business states. |
| Delivery data | Attempt number if supplied, request ID, endpoint response, processing error | Helps explain retries and operational failures. |
| Privacy controls | Retention class, redaction status, access classification | Prevents raw identity or biometric-related data from spreading through logs. |
Do not assume that an event ID is globally unique unless the provider says so. A safer database key may combine the provider account or environment with the event ID. Store raw payloads only when there is a documented operational or audit need, and restrict access to them. Logs should generally contain identifiers and diagnostic fields rather than document images, biometric templates, or full personal details.
2. A stable internal status model
Provider statuses rarely map one-to-one to product decisions. Create a small internal state model such as created, in progress, action required, approved, declined, manual review, and expired. Document which provider events can move a record between states.
Define whether transitions are monotonic. For example, a record marked approved should not return to in progress merely because an old event arrived late. If the provider can reopen or revoke a result, model that as an explicit transition with its own authorization and audit requirements. If your workflow also accepts verifiable credentials or wallet-based proof, keep credential status checking separate from KYC webhook state. The verifiable credential revocation and status checking guide covers that related operational concern.
3. Event classes and business actions
Group events by the action they require rather than by their names alone:
- Progress events: update a timeline but usually do not grant access.
- Input-needed events: notify the customer or return them to an incomplete step.
- Decision events: update eligibility only after validating the decision and its context.
- Review events: route the case to an approved manual-review process.
- Technical events: record provider or integration errors without presenting them as a customer decision.
For face match, liveness detection, document verification, or age verification online, avoid inventing a business conclusion from a single low-level signal. Map the provider’s documented result, confidence or reason fields, and your own policy together. Testing camera conditions and spoof scenarios should be handled as a separate test plan; see the liveness detection testing checklist.
Provider-agnostic webhook field reference
Before coding, create a mapping sheet with these columns:
- Provider field name and data type
- Required, optional, or conditionally present
- Allowed values and unknown-value behavior
- Internal field or state
- Whether the field is safe to log
- API or schema version introduced
- Test payload that exercises the field
Preserve unknown fields during development or capture them in a quarantined diagnostic record. Do not make a new, undocumented event type automatically grant access. A safe default is to acknowledge it, record that it was unsupported, and alert the integration owner when appropriate.
Cadence and checkpoints
Webhook reliability is not a one-time integration task. Use a recurring review schedule, with more frequent checks during launch or an API migration.
At every deployment or configuration change
- Confirm the endpoint URL, environment, tenant, and API version.
- Verify the signing secret or key reference is available through secret management, not source code.
- Send a test event for each important state transition.
- Test malformed signatures, stale timestamps, duplicate event IDs, unknown event types, and invalid JSON.
- Confirm that a provider retry does not repeat an account action.
- Check that sensitive payload fields are absent or redacted in application logs.
Weekly or monthly operational review
Choose a cadence that matches transaction volume and risk. Review:
- Received events compared with verification sessions expected to produce events
- Authentication failures and their source patterns
- Non-2xx responses, timeout rates, and processing latency
- Duplicate-event rate and idempotency conflicts
- Events stuck in an inbox, queue, or dead-letter store
- Records whose provider status and internal status disagree
- Manual interventions and the reason each was required
Quarterly or before a major release
- Read the provider’s current webhook and API version documentation.
- Compare production payloads with your field mapping and test fixtures.
- Review signing-key rotation and secret-revocation procedures.
- Test provider outage handling, queue recovery, and reconciliation.
- Review access to identity data, raw payloads, logs, and administrative replay tools.
- Confirm that customer notifications and appeal paths still match the product workflow.
For a broader evidence review, use the digital identity verification audit checklist. If the integration supports credential verification rather than only hosted KYC sessions, the credential verification API integration checklist provides a useful companion for data mapping and errors.
Integration monitoring worksheet
| Checkpoint | Measure or question | Owner | Action threshold |
|---|---|---|---|
| Delivery | Are expected events arriving within the normal provider and network delay? | Operations | Investigate a sustained increase or a gap in expected events. |
| Authentication | How many requests fail signature or timestamp validation? | Security | Separate configuration errors from unfamiliar traffic and investigate both. |
| Processing | What percentage is acknowledged but not completed? | Engineering | Inspect queue age, worker errors, and database failures. |
| Duplicates | How often is an already-seen event received? | Engineering | Confirm that duplicates are harmless and do not indicate a loop. |
| Reconciliation | Which provider cases disagree with internal records? | Operations | Fetch current state and resolve or document the difference. |
| Availability | Can the endpoint accept and durably record valid events? | Platform | Use an incident runbook if availability or queue capacity falls below the agreed level. |
How to interpret changes
Signature validation and replay protection checklist
Validate the request before using its contents. The implementation should generally:
- Receive the raw request body before JSON parsing or reformatting.
- Read the provider’s signature and timestamp headers exactly as documented.
- Recompute the signature with the correct secret or public-key method.
- Compare signatures using a suitable constant-time comparison.
- Reject requests outside the provider’s documented timestamp tolerance, when timestamps are part of the scheme.
- Record a safe diagnostic reason without storing secrets or unnecessary personal data.
- Use the event ID and, where appropriate, a payload hash to prevent replay or duplicate processing.
Signature validation proves message authenticity under the provider’s scheme; it does not prove that the business outcome is suitable for every action. Fetch the current verification record from the provider when your policy requires authoritative state, especially for high-impact decisions or events that contain only a summary.
Retry, idempotency, and ordering workflow
Assume that a valid event may arrive more than once, later than expected, or out of order. A practical processing sequence is:
- Validate the signature and basic request shape.
- Check whether the event ID has already been completed. If so, return a successful response without repeating side effects.
- Insert the event into an inbox table with a unique key and a pending status.
- Return a response once the event is durably stored, according to your availability design.
- Let a worker process the inbox record with a bounded retry policy.
- Before changing state, compare the event version, provider timestamp, or current provider state with the internal record.
- Apply the transition and record the resulting action in an audit trail.
- Mark the event completed, or move it to a dead-letter state with a reason after the retry limit.
Use database constraints or an equivalent atomic mechanism for idempotency. An in-memory “already processed” set is not sufficient after a restart or across multiple workers. Idempotency should cover downstream effects too: sending an approval email, enabling an account, creating a wallet credential, or starting a reverification task should each have a durable deduplication key.
Failure-handling examples
- Invalid signature: reject the request, create a security-relevant metric, and do not parse or act on the payload beyond safe diagnostics.
- Valid event, temporary database outage: return a failure if the event cannot be durably recorded, allowing provider retry, or route through a durable edge queue if your architecture supports one.
- Valid event, downstream email outage: keep the verification event recorded, retry the notification separately, and avoid asking the provider to resend the original event unnecessarily.
- Unknown event type: acknowledge only if your policy allows safe receipt without processing; record the schema version and alert for review.
- Out-of-order rejection followed by approval: use the documented provider state and transition rules rather than letting arrival order alone decide the final status.
- Persistent processing failure: place the event in a dead-letter queue or review list, preserve the error context, and provide a controlled replay tool.
A replay tool should require authorization, display the original event ID, show whether side effects have already occurred, and record who initiated the replay. Do not make “replay all” the default recovery action.
Interpreting operational signals
A rise in duplicate events may reflect provider retries caused by slow acknowledgments, a new delivery pattern, or an endpoint timeout. A rise in signature failures may indicate secret rotation drift, a proxy changing the body, a misconfigured environment, or unwanted traffic. A drop in event volume may indicate lower customer activity, a provider outage, a filtering rule, or a broken session-creation path. Compare webhook metrics with application traffic and verification-session creation before deciding what changed.
When records disagree, first distinguish a delayed event from a true state conflict. Fetch the provider’s current state when allowed, inspect the event timeline, and preserve the original evidence. Avoid silently overwriting an internal decision; route material conflicts through a documented review process. For account rechecks, connect the webhook workflow to a defined reverification policy such as the KYC reverification workflow guide.
When to revisit
Revisit this integration at least monthly or quarterly, depending on transaction volume and operational risk, and immediately after a material change. The strongest update triggers are:
- The provider changes event names, payload fields, signature requirements, retry behavior, or API versions.
- Your application adds a new verification method, market, account type, or high-impact decision.
- You introduce a queue, proxy, serverless endpoint, SDK, or middleware that changes request handling.
- Secret or signing-key rotation is planned or has failed.
- Monitoring shows more delays, duplicates, unknown events, authentication failures, or reconciliation gaps.
- An incident reveals that logs, replay controls, alerting, or manual review procedures are incomplete.
- Privacy, retention, accessibility, or customer-notification requirements for the workflow change.
Use this short action list for the next review:
- Export the last review’s delivery, authentication, latency, duplicate, and reconciliation measures.
- Compare them with the current provider documentation and your internal field map.
- Run a controlled test for approval, rejection, input-required, retry, duplicate, and unknown-event paths.
- Inspect one successful case and one failed or manually reviewed case from event receipt through final action.
- Confirm that sensitive identity data is retained only where needed and is excluded from routine logs.
- Document changes, assign owners, and set the next review date.
The objective is not to eliminate every retry or unusual event. It is to make each event authenticated, traceable, safe to process more than once, and visible when it needs human attention. Treat webhook behavior as part of the identity verification system itself, not as a small integration detail, and the workflow will be easier to operate during provider changes, API upgrades, incident response, and recurring reconciliation.