# iDenfy Webhooks

[iDenfy](https://www.idenfy.com) 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.

```javascript
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/idenfy-webhooks/references/verification.md).

> **For complete handlers with tests**, see [examples/express/](https://github.com/hookdeck/webhook-skills/tree/main/skills/idenfy-webhooks/examples/express/),
> [examples/nextjs/](https://github.com/hookdeck/webhook-skills/tree/main/skills/idenfy-webhooks/examples/nextjs/), [examples/fastapi/](https://github.com/hookdeck/webhook-skills/tree/main/skills/idenfy-webhooks/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](https://github.com/hookdeck/webhook-skills/blob/main/skills/idenfy-webhooks/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_AUTO_FINISHED` | Automated KYC review completed (check `final`: `false` means manual review follows) |
| `IDENTIFICATION_MANUAL_FINISHED` | 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_RESUBMITTED`,
`DOCUMENT_EXPIRATION`, `VIDEO_CALL_FINISHED`, `COMPANY_SUBMIT`, ...); see
[references/overview.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/idenfy-webhooks/references/overview.md). Deduplicate on `scanRef` (KYC) or `id`
(bank card): a failed delivery is retried.

## Environment Variables

```bash
IDENFY_WEBHOOK_SECRET=your_signing_key   # the Signing key set on the webhook

```

## Local Development

```bash
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](https://github.com/hookdeck/webhook-skills/blob/main/skills/idenfy-webhooks/references/overview.md) - How iDenfy webhooks work, events, payload, retries
* [references/setup.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/idenfy-webhooks/references/setup.md) - Configure the webhook and signing key
* [references/verification.md](https://github.com/hookdeck/webhook-skills/blob/main/skills/idenfy-webhooks/references/verification.md) - HMAC-SHA256 check, gotchas, debugging
* [examples/](https://github.com/hookdeck/webhook-skills/tree/main/skills/idenfy-webhooks/examples/) - Runnable Express, Next.js and FastAPI handlers with tests