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.
See the full list of available webhook events here: Webhook events →
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 30 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 30 seconds.
Return 2xx immediately, then process events asynchronously to avoid timeouts.
| Requirement | Details |
|---|---|
| Protocol | HTTPS with TLS 1.2+ |
| Response time | Return 2xx within 30 seconds |
| Capacity | Handle expected event volume |
| Idempotency | Process duplicates safely using eventId |
2. Configure webhooks on IDnow
Configure your webhooks on a flow-by-flow basis IDnow:
- Go to flow Settings: In the IDnow dashboard, go to your flow, and navigate to the Settings tab. Then scroll down to Webhooks.
- Create endpoint: Click "Add webhook" to open the configuration form.
- Add endpoint details: Enter your HTTPS endpoint URL and other details.
- Subscribe to events: Select specific events or receive all events by default.
- Set secret key: Provide a secret key for authentication in the headers section (optional).
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, verify the JWT signature by decoding the request body. See the Security page for details.
Process the event
- Return 2xx immediately: Respond within 30 seconds to acknowledge receipt.
- Check for duplicates: Use eventId to detect already-processed events.
- Queue for processing: Add the event to a background queue.
Prevent failures
Your endpoint must respond within 30 seconds. Responses taking longer are treated as failures and trigger retries.
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 9 times (10 total attempts) using exponential backoff (1s, 2s, 4s, 8s, 16s, 32s, 64s, 128s, 256s).
Retry conditions:
- Any non-2xx HTTP response (including 4xx and 5xx status codes)
- Network errors (timeout, connection refused)
- Endpoint unavailable
After all 10 attempts, the event is marked as MAX_ATTEMPTS_REACHED and no further retries are scheduled. For manual retrigger please reach out to IDnow.