How webhooks work
When a verification completes (or changes status), iDenfy sends an HTTP POST request to your configured webhook URL with the verification result.
Customer completes verification
↓
iDenfy processes (AI + human review)
↓
POST webhook to your endpoint
↓
Your server processes the result
Setting up webhooks
- Go to Dashboard → Settings → Webhooks)
- Enter your webhook URL (must be HTTPS)
- Select which events to receive
Your webhook endpoint must respond with a 2xx status code within 10 seconds. If it doesn’t, iDenfy will retry the delivery.
Webhook types
| Service | Webhook docs | Key statuses |
|---|
| KYC | KYC Webhooks → | APPROVED, DENIED, SUSPECTED, EXPIRED |
| KYB | KYB Webhooks → | Company verification results |
| AML | AML Monitoring → | Hit/no-hit on sanctions, PEPs, adverse media |
Webhook timing
iDenfy sends webhooks at different stages:
| Timing | When | Contains |
|---|
| Instant | Customer completes verification UI | Auto-check results (AI) |
| Prompt | Within minutes | Manual review results (human) |
| Delayed | Monitoring triggers | Ongoing AML monitoring hits |
The final field in the webhook payload indicates whether this is the definitive result. When final: true, no further webhooks will be sent for this verification.
Security
Always verify webhook authenticity:
- Callback signing — verify the HMAC signature on every webhook
- IP whitelisting — only accept requests from iDenfy’s IP ranges
Best practices
- Process asynchronously — acknowledge the webhook immediately (return 200), then process in the background
- Handle duplicates — use
scanRef as an idempotency key
- Log everything — store the full webhook payload for debugging and compliance
- Handle retries — if your endpoint is temporarily down, iDenfy will retry
- Verify signatures — never trust an unsigned webhook in production
