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-Signature header?
  • How do I handle IDENTIFICATION_AUTO_FINISHED and IDENTIFICATION_MANUAL_FINISHED events?
  • 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-TypeTriggered When
IDENTIFICATION_AUTO_FINISHEDAutomated KYC review completed (check final: false means manual review follows)
IDENTIFICATION_MANUAL_FINISHEDA human reviewer finalized the verification (always final: true)
IDENTIFICATION_EXPIREDThe verification token or session expired
IDENTIFICATION_CANCELLEDThe verification was cancelled
COMPANY_REVIEWA KYB company verification completed
AML_MONITORINGAn AML monitoring user was checked, accepted or declined

iDenfy documents 23 event types in total (also IDENTIFICATION_RESUBMITTED, 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


Repository

hookdeck/webhook-skills

v0.1.0 · MIT · Updated Nov 16, 2026

View on GitHub →