> For the complete documentation index, see [llms.txt](https://finext.gitbook.io/one-kyc/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://finext.gitbook.io/one-kyc/admin/webhooks.md).

# Webhooks

The **Webhooks** section configures notifications for verification events. OneKYC sends HTTP requests to the URLs you provide when specific events happen (session created, step completed, verification approved or rejected, and others).

## Endpoints

An endpoint is a URL on your server that receives OneKYC notifications. You can create several endpoints for different purposes and environments.

### Creating an endpoint

When you create a new endpoint, set the following parameters:

* **URL** — the address on your server that receives notifications. HTTPS is required.
* **Description** — explains the endpoint's purpose (for example, "Production CRM", "Analytics system").
* **Environment** — sandbox or production. Determines which environment's events are sent to this URL.
* **Event types** — the list of events to receive notifications for:
  * **All events** (`*`) — notifications for every event type.
  * **Selected events** — a custom set (for example, `verification.approved`, `verification.declined`, `step.completed`).
  * **KYB events** — events related to business verification (for example, `kyb.business.verified`) are listed in a separate category.

The full list of event types is in [Webhooks API](/one-kyc/api/webhooks.md) and [KYB Webhooks](/one-kyc/kyb/webhooks.md).

### Signing secret

After you create the endpoint, the system generates a **signing secret** with a `whsec_` prefix. The secret is used to verify the authenticity of incoming requests on your side.

{% hint style="warning" %}
The secret is shown **once** at creation. Save it in a secure vault immediately.
{% endhint %}

### Rotating the secret

When you need to update the secret (scheduled rotation or suspected compromise):

1. Open the endpoint card.
2. Trigger secret rotation.
3. During the **grace period**, both secrets (old and new) are accepted simultaneously, which lets you update the signature-check code on your side without losing notifications.
4. When the grace period ends, the old secret stops working.

## Delivery log

The **"Logs"** (or **"Deliveries"**) sub-section shows the notification delivery history:

| Field               | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| **Time**            | Date and time of delivery                                                  |
| **URL**             | Endpoint address                                                           |
| **Event**           | Event type sent                                                            |
| **Response status** | HTTP code returned by your server (2xx — success, anything else — failure) |
| **Attempts**        | Number of delivery attempts                                                |

When you open delivery details you can see the request body, headers, and your server's response. This helps diagnose issues with notification receipt and signature verification.

### Resend

For a specific failed delivery, the **"Resend"** action redelivers the notification to the same endpoint.

## Retry policy

When delivery fails (your server did not respond or returned an error code), OneKYC retries automatically:

* **Maximum attempts** — up to 5.
* **Strategy** — exponential backoff: base delay 5 seconds, doubled on each attempt, capped at 24 hours. A random jitter of ±20% is applied to spread the load.
* When all attempts are exhausted, the event is moved to the dead-letter queue (DLQ) — see below.

## Dead-letter queue (DLQ)

The **Dead Letter Queue** sub-section lists events for which all automatic delivery attempts have been exhausted. Available actions:

* **Resend a single event** (`Retry`) — the notification is redelivered to the same endpoint.
* **Bulk retry** (`Retry all`) — every event from the DLQ for the chosen endpoint is resent (typically used after the receiver has been restored).
* **Delete event** (`Delete`) — the event is removed from the DLQ without being sent.

Every bulk action and retry is recorded in the audit log.

## Statistics and payload examples

* **Delivery statistics** — summary metrics per endpoint (number of sends, successful deliveries, failures, average response time).
* **Payload example** for each event type — shows the request body structure sent to the endpoint when the event fires. Use it for offline debugging of your handler code.

## Testing

Two tools verify that an endpoint is set up correctly:

### Ping

Sends a simple request without payload to check that your server is reachable. The result shows whether the endpoint responds and with what HTTP code.

### Test event

Sends a test event with sample data (for example, `verification.approved` with a test payload). It is used to verify:

* That request routing works correctly on your side.
* That HMAC signature verification works.
* That your application processes the payload structure correctly.

The test send result appears in the delivery log.