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 event_id to prevent duplicate operations

Track event_id 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.

Requirement	Details
Protocol	HTTPS with TLS 1.2+
Response time	Return 2xx within 10 seconds
Capacity	Handle expected event volume
Idempotency	Process duplicates safely using event_id

---

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 event_id 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 3 times:

Attempt	Delay	Total elapsed time
1st retry	2 seconds	2s
2nd retry	4 seconds	6s
3rd retry	8 seconds	14s

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.