Webhook events

Understand webhook event types and payload structure

Webhooks allow you to receive real-time notifications about identification status changes. When enabled for your account, IDnow sends HTTP POST requests to your configured endpoint URL after key events in the identification lifecycle. To activate webhooks, contact your IDnow technical account manager.

Payload structure

The webhook body is identical to the JSON you receive when you call the GET Identification endpoint for the same ident. There is no additional envelope wrapper.

Example of Payload

{
  "identificationprocess": {
    "result": "SUCCESS",
    "reason": "...",
    "companyid": "your-company",
    "transactionnumber": "12345",
    "id": "ABC-DEFGH",
    "filename": "12345.zip",
    ...
  },
  "customdata": { ... },
  "contactdata": { ... },
  "userdata": { ... },
  "identificationdocument": { ... },
  "attachments": { ... }
}

See Get Identification for the full response structure.

---

Webhook Types

Different webhook types are sent at different stages of the identification lifecycle:

Type	When it is sent
START	User starts the ident process in the app
REALTIME	User completes the in-app flow; preliminary data available but ident is still under review
CHECK_PENDING	(Type of REALTIME) At least one automated check was inconclusive; manual review required
REVIEW_PENDING	(Type of REALTIME) Automated checks passed but full manual review is enforced by your configuration
ABORTED	User quit the identification process before completing
FINAL	Review completed; final result available (SUCCESS, SUCCESS_DATA_CHANGED, or FRAUD_SUSPICION_CONFIRMED)
CANCELED	Agent cancelled the ident after review (e.g., image quality too poor)

caution

Treat REALTIME webhooks as preliminary only. Always wait for the FINAL webhook before acting on a result. In rare cases, a FINAL webhook may arrive and then be superseded by a corrected result from a supervisor review.

Preliminary Result

Preliminary result statuses are delivered through REALTIME webhooks. To receive them, your account must be configured to accept REALTIME webhooks. The result field can take the following preliminary values (see Status and result values for the full reference):

Value	Type	Description
REVIEW_PENDING	Preliminary	The user has completed the identification and it is awaiting review. The final result is expected to be SUCCESS or SUCCESS_DATA_CHANGED. For real-time flows, treat this as a successfully verified identification.
FRAUD_SUSPICION_PENDING	Preliminary	The user has completed the identification but a fraud suspicion was raised. The final result is expected to be FRAUD_SUSPICION_CONFIRMED. For real-time flows, treat this as pending or failed.

caution

A preliminary result is not final. Always wait for the matching FINAL webhook before persisting an outcome — a senior-review correction can change the result.

---

Authentication

IDnow supports basic authentication (username and password) for webhook delivery. Contact your IDnow technical account manager to configure webhook authentication credentials.

Retry Logic

Webhooks are automatically retried on failure using exponential back-off:

• Schedule: 1s → 2s → 4s → 8s → 16s … (doubling each attempt)
• Maximum retry time: 1 day
• Warning email: Sent after 10 seconds without successful delivery
• Success codes: Any 2xx HTTP status is considered successful
• Retry codes: 3xx, 4xx, 5xx responses trigger a retry

note

If a webhook fails and the identification changes in the meantime (e.g., a REALTIME webhook fails and the ident moves to FINAL), the outdated webhook is not retried. You will receive a warning email with subject: IDnow Webhook Error: Not sending for <transactionnumber> since identification was changed.

Warning and Error Emails

The recipient is the technical contact defined during account setup.

Email subject	Meaning
IDnow Webhook Warning: Unable to send for <transactionnumber>. Retrying.	Delivery failed; retrying
IDnow Webhook Error: Unable to send for <transactionnumber>. Giving up.	Max retry time reached; webhook abandoned

Source IP Addresses

Whitelist these source IPs on your webhook endpoint:

Environment	IP Addresses
Live	213.95.145.0/27
Live CH	193.169.187.168/32
Test	52.30.27.5/32, 52.48.216.0/32
Test CH	52.18.79.87

---

Best Practices

Reliability

• Respond with an HTTP 2xx status within the timeout window to prevent unnecessary retries
• Process webhooks asynchronously — return 200 immediately, then process in the background
• Implement idempotency: the same webhook may be delivered more than once; use the transactionnumber or id (IdentID) to deduplicate

Security

• Use HTTPS endpoints only
• Configure basic authentication with your IDnow account manager
• Restrict your webhook endpoint to the IDnow source IP ranges listed above

Testing

Use a tool like ngrok to expose a local server during development:

ngrok http 3000
# Use the generated HTTPS URL as your webhook endpoint

Common Issues

Timeout Errors

• Ensure your endpoint responds within a few seconds
• Return 200 immediately and process the event asynchronously

Duplicate Delivery

• Implement idempotency using the transactionnumber or IdentID
• Use database constraints to prevent duplicate records

Missing Webhooks

• Verify the webhook URL is publicly accessible over HTTPS
• Check your firewall allows traffic from the IDnow source IPs
• Confirm the webhook feature is enabled for your account (contact your account manager)