> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Webhooks Overview

> Understand how iDenfy webhooks deliver verification results via HTTP POST, including setup, payload structure, and retry handling.

## 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

1. Go to [Dashboard → Settings → Webhooks](/guides/dashboard/settings/system-notifications-webhooks-emails)
2. Enter your webhook URL (must be HTTPS)
3. Select which events to receive

<Warning>
  Your webhook endpoint must respond with a **2xx status code** within **10 seconds**. If it doesn't, iDenfy will retry the delivery.
</Warning>

## Webhook Types

| Service | Webhook docs                                 | Key statuses                                 |
| ------- | -------------------------------------------- | -------------------------------------------- |
| **KYC** | [KYC Webhooks →](/kyc/webhooks)              | APPROVED, DENIED, SUSPECTED, EXPIRED         |
| **KYB** | [KYB Webhooks →](/kyb/webhooks)              | Company verification results                 |
| **AML** | [AML Monitoring →](/aml/monitoring-retrieve) | 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   |

<Note>
  The `final` field in the webhook payload indicates whether this is the definitive result. When `final: true`, iDenfy will not send any further webhooks for this verification.
</Note>

## Security

Always verify webhook authenticity:

1. **[Callback signing](/security/callback-signing)** — verify the HMAC signature on every webhook
2. **[IP whitelisting](/security/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