Guide to iDenfy Webhooks: Features and Best Practices
iDenfy is an identity verification platform covering KYC document and selfie checks, KYB company onboarding, AML screening and monitoring, plus bank, bank-card, facial-authentication and age-estimation products. A verification can finish automatically in seconds or wait for a human reviewer, and an AML check can change status months later. iDenfy's webhooks, which its dashboard calls system notifications, are how your onboarding flow finds out.
This guide covers how iDenfy's per-event webhooks are configured, which events carry a final decision, verifying Idenfy-Signature with a key you set yourself, and the 10-second response limit.
What are iDenfy webhooks?
In iDenfy, a webhook is created for one event type at a time. Each has its own receiver URL, custom headers, signing key, optional OAuth, retry settings and failure email. When the event occurs, iDenfy sends a JSON POST with the event name in the Idenfy-Event-Type header; the body itself doesn't say which event it is.
KYC results can arrive more than once for the same verification. An automatic result comes first, and if the case goes to manual review, a second webhook follows with the reviewer's decision. The final flag in the body tells you whether more are coming.
Signing is optional per webhook. If you set a signing key, iDenfy adds Idenfy-Signature, a hex HMAC-SHA256 of the raw body.
iDenfy webhook features
| Feature | Details |
|---|---|
| Configuration | Settings > System notifications, one webhook per event type |
| Signature | hex HMAC-SHA256 |
| Signature header | idenfy-signature |
| Signed content | The raw request body |
| Key | A signing key you choose, per webhook. No header without one |
| Body | JSON |
| Event routing | Header field Idenfy-Event-Type |
| Timeout | 10 seconds |
| Retries | Count and fixed interval set per webhook; no documented default |
| After retries | Failure email (if configured) and manual Resend |
| TLS | HTTPS with a CA-issued certificate; self-signed is rejected |
| Source IPs | Available from support on request, subject to change |
Events and payloads
Idenfy-Event-Type | Triggered When | Common Use Cases |
|---|---|---|
IDENTIFICATION_ | Automated KYC review completed (seconds after the user finishes) | Act on an instant result; wait for final: true for a definitive one |
IDENTIFICATION_ | A human reviewer finalised the verification (always final: true) | Final approve/deny after a preliminary result |
IDENTIFICATION_EXPIRED | The verification token or session expired | Prompt the user to restart |
IDENTIFICATION_CANCELLED | The verification was cancelled by the user, system or API | Clean up pending state |
COMPANY_REVIEW | A KYB company verification completed | Onboard or reject a business |
AML_MONITORING | An AML monitoring user was checked, accepted or declined | Sanctions/PEP/adverse-media alerts |
Other documented events include IDENTIFICATION, IDENTIFICATION_, DOCUMENT_EXPIRATION, VIDEO_CALL_FINISHED, COMPANY_DELETE, COMPANY_AML_REVIEW, COMPANY_INFO_REQUEST, COMPANY_EXPIRATION, COMPANY_SUBMIT, GOV_ORDERED_DOCUMENT, SOS_REPORT, AML_, BANK_VERIFICATION, ACCOUNT_CHECK and
The dashboard lists the same events under display names (ID VERIFICATION AUTO FINISHED, COMPANY REVIEW and so on). iDenfy's legacy IDENTIFICATION page refers to the newer events as ID_VERIFICATION_*, but the header carries IDENTIFICATION_*, so match on that.
Event Payload Structure
Each product has its own body schema. KYC bodies include scanRef (the verification's unique ID), clientId, a status object with the overall result (APPROVED, DENIED, SUSPECTED, EXPIRED), document and face-match data, and a boolean final. Once a webhook with final: true arrives, iDenfy sends nothing more for that verification. Bank-card results carry an id instead.
iDenfy's OpenAPI files give the schemas with per-field examples, but no complete body for any event, and VIDEO_CALL_FINISHED has no body schema at all. Use the dashboard's Test button and a sandbox verification to collect real samples.
Setting up iDenfy webhooks
Prerequisites
- An iDenfy account with access to dashboard settings
- A public HTTPS endpoint with a certificate from a trusted CA
How Do I Get the Signing Key?
Hookdeck setup: Set a signing key on the iDenfy webhook. Without one, deliveries are unsigned and fail verification.
iDenfy doesn't generate the key. You choose a secret and enter it:
- In the iDenfy dashboard, go to Settings > System notifications.
- Click the webhook you want to protect to expand it.
- Open the Headers section and set the Signing key field.
- Put the same value in
WEBHOOK_SECRET, with no trailing whitespace.
Because every event type has its own webhook, it's easy to end up with different keys on different webhooks. A receiver checks one key, so either use the same key on every webhook that points at one URL, or give each key its own URL.
Register Your Endpoint
- In Settings > System notifications, choose Create new and pick the event type, or open an existing webhook.
- Enter your HTTPS URL, for example
https://example.com/webhooks/idenfy. - Set the signing key, the retry count and interval, and a failure email address.
- Save, then use Test to send a test request.
- Repeat for each event type you need, such as
ID VERIFICATION AUTO FINISHED,ID VERIFICATION MANUAL FINISHEDandCOMPANY REVIEW.
Test a delivery
Start a local receiver and forward requests with the Hookdeck CLI:
npx hookdeck-cli listen 3000 idenfy --path /webhooks/idenfy
The CLI's public URL has a valid certificate, so iDenfy accepts it. Point one webhook at it, press Test, and check that Idenfy-Event-Type and Idenfy-Signature arrive as expected.
Securing iDenfy webhooks
Compute HMAC-SHA256 over the raw body using the signing key as a plain UTF-8 string, encode it as hex, and compare it with Idenfy-Signature in constant time. iDenfy sends lowercase hex. The callback signing page has samples in several languages.
const crypto = require('node:crypto');
function verifySignature(rawBody, headers, secret) {
if (!Buffer.isBuffer(rawBody) || typeof secret !== 'string' || !secret) return false;
const signature = headers['idenfy-signature'];
if (typeof signature !== 'string') return false;
const key = Buffer.from(secret, 'utf8');
const message = rawBody;
const candidates = [signature];
const expected = crypto.createHmac('sha256', key).update(message).digest();
return candidates.some((candidate) => {
if (!/^[0-9a-fA-F]{64}$/.test(candidate)) return false;
const received = Buffer.from(candidate, 'hex');
return received.length === expected.length && crypto.timingSafeEqual(received, expected);
});
}
This handler routes on the header, stores interim KYC results, and only finalises an applicant when final is true.
const express = require('express');
function createIdenfyApp({ alreadyHandled, saveInterim, finalise, handleOther }) {
const app = express();
app.post('/webhooks/idenfy', express.raw({ type: '*/*' }), async (req, res) => {
const secret = process.env.WEBHOOK_SECRET;
if (!secret) return res.sendStatus(500);
if (!verifySignature(req.body, req.headers, secret)) return res.sendStatus(401);
const eventType = req.headers['idenfy-event-type'];
let body;
try {
body = JSON.parse(req.body.toString('utf8'));
} catch {
return res.sendStatus(400);
}
if (!body || typeof body !== 'object' || Array.isArray(body)) return res.sendStatus(400);
if (!body.scanRef && !body.id) return res.sendStatus(400);
try {
const ref = body.scanRef || body.id;
if (await alreadyHandled(`${eventType}:${ref}`)) return res.sendStatus(200);
if (eventType === 'IDENTIFICATION_AUTO_FINISHED' || eventType === 'IDENTIFICATION_MANUAL_FINISHED') {
if (body.final) await finalise(body.scanRef, body.status);
else await saveInterim(body.scanRef, body.status);
} else {
await handleOther(eventType, body);
}
} catch {
return res.sendStatus(503);
}
return res.sendStatus(200);
});
return app;
}
There's no timestamp in the signature, so a captured request stays valid. Deduplicating on the event type plus scanRef (or id for bank cards) keeps a replay or retry from repeating an action, while still letting the manual result through after the automatic one.
Hookdeck's iDenfy source type checks Idenfy-Signature against the raw body with the key you enter. It responds 200 to iDenfy for every request, so a mismatch never triggers iDenfy's retries; instead, Hookdeck records it as failed verification and keeps it from your destination. No timestamp limit applies. If you choose not to set a signing key on iDenfy, leave verification off on the source.
Make iDenfy webhooks production-ready. Hookdeck Event Gateway answers iDenfy well inside the 10-second limit, verifies each result, and keeps every KYC and AML decision replayable.
iDenfy webhook limitations and pain points
A 10-second timeout
The Problem: Requests time out and are retried while your service is still processing them.
Why It Happens: iDenfy waits 10 seconds for a 2xx. Downloading images, calling a CRM or updating several records in-line can take longer.
Workarounds:
- Store the body and respond before doing anything else.
- Fetch images and detailed data in a background job.
How Hookdeck Can Help: Hookdeck responds to iDenfy immediately and gives your destination its own, configurable timeout.
Retry policy is up to you, with no default documented
The Problem: A webhook created with low retry settings gives up quickly during an outage.
Why It Happens: iDenfy retries the number of times configured on each webhook, at a fixed interval, and doesn't document a default. Once retries are exhausted, recovery is a failure email and a manual Resend.
Workarounds:
- Review the retry settings on every webhook and configure a failure email.
- Reconcile pending verifications against the iDenfy API after an incident.
How Hookdeck Can Help: Hookdeck accepts each delivery on the first attempt, so iDenfy's retry budget isn't spent on your downtime, and its own retries and replays cover recovery.
Many webhooks, many keys
The Problem: Some events verify and others don't, or one event type stops arriving after a change.
Why It Happens: Every event type is its own webhook with its own URL and signing key, and signing is skipped entirely on a webhook with no key.
Workarounds:
- Keep a list of every configured webhook with its URL and key.
- Use one key per receiver URL.
How Hookdeck Can Help: Hookdeck's request log shows which event types are arriving and which fail verification, which quickly exposes a webhook with the wrong key or none.
Multiple results per verification
The Problem: An applicant is approved, then denied, or onboarded twice.
Why It Happens: An automatic result can be followed by a manual one for the same scanRef, and only the last has final: true.
Workarounds:
- Treat results with
final: falseas provisional. - Key processing on event type plus
scanRef.
How Hookdeck Can Help: Hookdeck filters can route final and provisional results to different destinations based on the body's final field.
No published IP range
The Problem: You can't restrict the endpoint to iDenfy's network from the documentation alone.
Why It Happens: iDenfy provides its webhook IPs only through a support request and notes that they can change.
Workarounds:
- Request the current list from support if your policy requires it, and plan for updates.
- Make the signature check mandatory.
How Hookdeck Can Help: With Hookdeck receiving iDenfy's requests, your firewall only needs to admit Hookdeck.
Best practices
Set a key on every webhook
An unsigned webhook is an unauthenticated KYC decision. Set a signing key on each one and keep the receiver rejecting requests without a valid header.
Route on the header, not the body
The body doesn't name the event. Read Idenfy-Event-Type, or give each webhook its own path.
Respect final
Hold provisional KYC outcomes until the final one arrives, or design your flow so a later result can override an earlier one.
Acknowledge quickly and process later
Store the verified request and return 2xx well inside 10 seconds. Our guide to asynchronous webhook processing shows the pattern, and the idempotency guide covers recording scanRef alongside the change.
Handle personal data carefully
Bodies contain names, document details and face-match data. Keep them out of general logs and apply retention rules to any store that holds them.
Conclusion
iDenfy gives you a lot of control: one webhook per event type, your own signing key and your own retry settings. That control is also the risk, since a webhook without a key or with weak retry settings fails quietly. Set keys everywhere, respond within 10 seconds, and let final decide when a verification is done.
Hookdeck Event Gateway makes the timeout and retry settings less critical by accepting every iDenfy result first and keeping it replayable.
Get started with Hookdeck for free and handle iDenfy webhooks reliably in minutes.