Skip to main content

Manage webhooks

Set up webhook endpoints, manage subscriptions, and monitor delivery​

IDnow sends HTTP webhooks for each session. Webhooks allow you to keep your system in sync and let you know when new results or data blocks are ready.

Note that session steps are asynchronous.

info

See the full list of available webhook events here: Webhook events →

info

Key characteristics: - Thin payloads only (never contains PII) - All events sent by default - Asynchronous delivery (order not guaranteed) - Automatic retries for transient failures

Checklist​

Before receiving webhooks, complete these steps:

1. Expose a secure HTTPS endpoint

Your endpoint must support TLS 1.2 or higher for receiving POST requests.

2. Only allow incoming requests from IDnow's IPs

Block unauthorized sources by accepting requests only from documented IDnow IPs.

3. Enable JWT signature verification (recommended)

Use our signed JWT to verify webhook authenticity and prevent spoofing.

4. Respond with HTTP 2xx within 10 seconds

Return a success status quickly and process events asynchronously in the background.

5. Use eventId to prevent duplicate operations

Track eventId to detect and skip duplicate deliveries caused by retries.

Configure webhooks​

Webhook endpoints are fully manageable after creation. You can update an existing endpoint at any time like adjusting its URL, description, or security settings or delete it completely if it's no longer required.

1. Enpoint requirements​

Your endpoint must support HTTPS with TLS 1.2+ and return HTTP 2xx within 10 seconds.

tip

Return 2xx immediately, then process events asynchronously to avoid timeouts.

RequirementDetails
ProtocolHTTPS with TLS 1.2+
Response timeReturn 2xx within 10 seconds
CapacityHandle expected event volume
IdempotencyProcess duplicates safely using eventId

2. Configure webhooks on IDnow​

Configure your webhooks on a flow-by-flow basis IDnow:

  1. Go to flow Settings: In the IDnow dashboard, go to your flow, and navigate to the Settings tab. Then scroll down to Webhooks.
  2. Create endpoint: Click "Add webhook" to open the configuration form.
  3. Add endpoint details: Enter your HTTPS endpoint URL and other details.
  4. Subscribe to events: Select specific events or receive all events by default.
  5. Set secret key: Provide a secret key for authentication in the headers section (optional).
info

Configure separate endpoints for staging, and live environments. You can update an existing endpoint, including its URL, after creation.

3. Handle webhooks​

Verify the source​

Validate IP address

Accept requests only from IDnow's documented IP ranges.

Verify JWT signature

Optionally, use your secret key to validate the JWT in the request header. See the Security page for details.

Process the event​

  1. Return 2xx immediately: Respond within 10 seconds to acknowledge receipt.
  2. Check for duplicates: Use eventId to detect already-processed events.
  3. Queue for processing: Add the event to a background queue.

Prevent failures​

Your endpoint must respond within 10 seconds. Responses taking longer are treated as failures and trigger retries.

tip

Process webhook events asynchronously. Acknowledge receipt immediately (return HTTP 2xx) and queue the event for background processing.

Retry logic​

IDnow automatically retries failed deliveries up to 10 times by default using exponential backoff (1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s, 512s), capped at a maximum interval of 1 hour.

Retry conditions:

  • Transient errors (5xx status codes)
  • Network errors (timeout, connection refused)
  • Endpoint unavailable

No retry for:

  • Client errors (4xx status codes)
  • Authentication failures
  • Invalid endpoint URL

After maximum retries, the event is moved to the dead letter queue. For manual retrigger please reach out to IDnow.