Webhooks notify your service when something happens — a verification completes, an applicant skips a step, a manual review is requested. You register an HTTPS endpoint, pick the events, and the platform POSTs a signed payload.

## Before you start

You need **Owner** or **Admin** access. Webhook endpoints are configured per mode — endpoints registered in test mode receive only test-mode events. Switch mode in the sidebar before registering. See [Modes and regions](/developers/modes-and-regions).

## Register an endpoint

Open **Developers → Webhooks** and click **New subscription**. Enter the receiver URL. The URL must start with `https://`. Plain HTTP is rejected so your signing secret cannot leak. Pick the events you want.

On submit, we generate a 32-byte signing secret and return it once. Copy it into a secrets manager — it is never retrievable again. If you lose the secret, rotate it (see [Verify webhook signatures](/developers/webhooks-verify-signatures)).

## Choose event types

These events are delivered today:

- `kyc.session.completed` — verification finished, terminal outcome assigned.
- `kyc.session.cancelled` — verification cancelled by the operator.
- `kyc.session.manual_review_requested` — the verification was parked for human review.

These event types are reserved and accepted on a subscription, but no delivery is produced for them. Subscribing to them is harmless and forward-compatible; build your receiver to handle them when deliveries begin, without assuming they currently arrive:

- `kyc.session.expired` — the applicant did not finish before the link expired.
- `kyc.session.skipped_by_applicant` — the applicant skipped a step, ending the verification.

Naming follows `kyc.<domain>.<state>` so you can pattern-match on the prefix. Your receiver should handle unknown `event.type` values defensively (log and ignore, do not error) — new event types can ship without a code change on your side.

## The event payload

Every `kyc.session.*` delivery carries a compact JSON body with reference fields only — no applicant personal data:

```json
{
  "sessionId": "vs_01J9X2Y3Z4A5B6C7D8E9F0G1H2",
  "status": "completed",
  "outcome": "approved",
  "occurredAt": "2026-06-16T12:34:56.000Z"
}
```

- `sessionId` — the verification id. Use it to fetch full detail from the REST API.
- `status` — the terminal status at emit time.
- `outcome` — the assigned verification outcome, or `null` for a transition that carried no verdict.
- `occurredAt` — UTC ISO-8601 timestamp of the transition.

The payload is **additive within a version**: a new optional field may be added without breaking your receiver, and a breaking change ships as a new event version. Parse defensively and ignore fields you do not recognize. The webhook is an integration trigger, not a data export — fetch authoritative detail by `sessionId` from the API.

## Test the delivery

After saving the subscription, send a test request from your client to confirm signature verification. The [Verify webhook signatures](/developers/webhooks-verify-signatures) page shows the exact algorithm, header format, and tolerance window. Real events fire when the underlying state transition happens.

## Inspect deliveries in the console

The subscription list at **Developers → Webhooks** shows each endpoint, the events it receives, and the last successful and unsuccessful delivery times. Open a subscription to see its full delivery history, replay individual deliveries, and rotate the signing secret.

## Inspect deliveries programmatically

The same delivery log is available over the REST API at `GET /v1/webhook-events`. It is cursor-paginated and returns one row per delivery attempt, with the status, HTTP code, latency, attempt count, and a bounded error code. Filter by `session_id` to trace one verification's deliveries, or by `subscription_id` to inspect one endpoint. The response never includes the signing secret or the event payload. See the [API reference](/reference) for the full schema.

## Next steps

- Verify every delivery: [Verify webhook signatures](/developers/webhooks-verify-signatures).
- Recover from failures: [Replay and troubleshoot webhook deliveries](/developers/webhooks-replay-and-troubleshoot).