Agent skill
iDenfy Webhooks Skill
Receive and verify iDenfy webhooks. Use when setting up an iDenfy system notification endpoint, verifying the Idenfy-Signature header (HMAC-SHA256 of the raw body, hex), debugging signature failures, or handling events like IDENTIFICATION_AUTO_FINISHED, IDENTIFICATION_MANUAL_FINISHED, COMPANY_REVIEW and AML_MONITORING.
Install this skill
npx skills add hookdeck/webhook-skills --skill idenfy-webhooks
iDenfy is an identity verification, KYB and AML platform. Its webhooks (called "system notifications") report KYC verification results, company (KYB) reviews, AML monitoring, bank, bank-card, facial-authentication and age-estimation results. Each webhook is configured per event type in the dashboard. When you set a signing key on a webhook, every delivery carries an Idenfy-Signature header: the hex HMAC-SHA256 of the raw request body.
When to Use This Skill
- How do I receive iDenfy webhooks?
- How do I verify the
Idenfy-Signatureheader? - How do I handle
IDENTIFICATION_andAUTO_ FINISHED IDENTIFICATION_events?MANUAL_ FINISHED - How do I handle KYB (
COMPANY_REVIEW) and AML (AML_MONITORING) notifications? - Why is my iDenfy webhook signature verification failing?
Verification (core)
Idenfy-Signature is the bare lowercase hex HMAC-SHA256 of the raw request body: no prefix, no timestamp. The key is the signing key you set on the webhook, used as a UTF-8 string (not hex- or base64-decoded). Check the header is exactly 64 hex characters before decoding, because Buffer.from(x, 'hex') silently truncates invalid input.
const crypto = require('crypto');
function verifyIdenfySignature(rawBody, signature, secret = process.env.IDENFY_WEBHOOK_SECRET) {
if (!secret || typeof signature !== 'string') return false;
if (!/^[0-9a-f]{64}$/i.test(signature)) return false; // also guards the hex decode
const expected = crypto.createHmac('sha256', secret).update(rawBody).digest();
return crypto.timingSafeEqual(expected, Buffer.from(signature, 'hex'));
}
// rawBody: Buffer from express.raw({ type: '*/*' }); signature: req.headers['idenfy-signature']
Return 401 when this fails (including a missing header), 400 for a body that isn't a JSON object, and 200 once handled. In Python use hmac.compare_digest on bytes (encode both sides) so a non-ASCII header gives 401, not 500. Details in references/verification.md.
For complete handlers with tests, see examples/express/, examples/nextjs/, examples/fastapi/.
Setup
Hookdeck setup: Set a signing key on the iDenfy webhook. Without one, deliveries are unsigned and fail verification.
In the iDenfy dashboard go to Settings → System notifications, click the webhook to expand it, open Headers and set the Signing key field. iDenfy does not generate the key: you choose it. Each event type's webhook can have its own key, so one verifier (or one Hookdeck source) covers one key. Full steps in references/setup.md.
Event Types
Dispatch on the Idenfy-Event-Type request header (the body does not name the event). The dashboard shows display names such as ID VERIFICATION AUTO FINISHED; the header carries the enum value below.
Idenfy-Event-Type | Triggered When |
|---|---|
IDENTIFICATION_ | Automated KYC review completed (check final: false means manual review follows) |
IDENTIFICATION_ | A human reviewer finalized the verification (always final: true) |
IDENTIFICATION_EXPIRED | The verification token or session expired |
IDENTIFICATION_CANCELLED | The verification was cancelled |
COMPANY_REVIEW | A KYB company verification completed |
AML_MONITORING | An AML monitoring user was checked, accepted or declined |
iDenfy documents 23 event types in total (also IDENTIFICATION_, DOCUMENT_EXPIRATION, VIDEO_CALL_FINISHED, COMPANY_SUBMIT, ...); see references/overview.md. Deduplicate on scanRef (KYC) or id (bank card): a failed delivery is retried.
Environment Variables
IDENFY_WEBHOOK_SECRET=your_signing_key # the Signing key set on the webhook
Local Development
npx hookdeck-cli listen 3000 idenfy --path /webhooks/idenfy
No account required. Use the printed URL as the webhook URL in iDenfy.
Resources
- references/overview.md - How iDenfy webhooks work, events, payload, retries
- references/setup.md - Configure the webhook and signing key
- references/verification.md - HMAC-SHA256 check, gotchas, debugging
- examples/ - Runnable Express, Next.js and FastAPI handlers with tests