Webhooks: overview
# Webhooks: overview
Webhooks are the canonical way to learn that a verification finished. Polling works but it's lossy under retries and expensive at scale.
## How they work
1. You register an HTTPS endpoint in the dashboard ([Developer → Webhooks](/docs/self-enterprise/dashboard/webhooks/)) and get the signing secret when you save it. (You can send a test request afterwards to confirm it's reachable.)
2. When an event fires, we POST a JSON payload to your endpoint, signed so you can verify it came from us.
3. Your handler verifies the signature (via the SDK) and processes the event.
4. You return `2xx` to acknowledge. A `408`, `429`, `5xx`, or timeout triggers a retry; any other `4xx` is treated as a permanent rejection and not retried.
## What we send
A single POST with a JSON body, typed as `WebhookEvent`. One event is delivered:
| Event type | Fires when |
| ------------------------ | ----------------------------------------------------- |
| `verification.completed` | Off-chain verification finishes (success or failure). |
See [Event catalog](/docs/self-enterprise/webhooks/events/) for the full payload.
## Ordering and delivery guarantees
- **At-least-once.** The same event can arrive more than once (a retry after a failed delivery, a network blip). Make your handler idempotent.
- **Bounded latency.** Typically under a second from verification to delivery. Under retry backoff, latency can grow to minutes.
## Idempotency
The event carries a stable ID derived from the verification, so retries of the same event share it:
- `verification.completed`: `<verification_id>-completed`
Dedupe in your handler on `verification_id`. See [Best practices](/docs/self-enterprise/webhooks/best-practices/).
## Reliability
Failed deliveries (`408`, `429`, `5xx`, timeout, or connection error) are retried automatically on an exponential schedule over a span of days, so a brief outage on your side recovers on its own. Any other `4xx` response is a permanent rejection and is not retried, so never return `400` for a transient failure like a database hiccup (see [Best practices](/docs/self-enterprise/webhooks/best-practices/#6-return-the-right-status-codes)). Every delivery is signed, see [Verify webhooks](/docs/self-enterprise/webhooks/verify-webhooks/).
:::warning
For [Custom Config](/docs/self-enterprise/workspaces/custom-config/) flows the webhook delivery is the **only copy** of the verification result and disclosed data: Self stores none of it (`storage_state: 'skipped'`). Persist the payload before returning `2xx`. This is also why a live Custom Config can't deploy or create sessions until your organization has an active live endpoint.
:::
Read https://docs.self.xyz/docs/self-enterprise/webhooks/overview.md so I can ask questions about this Self documentation page.
Webhooks are the canonical way to learn that a verification finished. Polling works but it’s lossy under retries and expensive at scale.
How they work
- You register an HTTPS endpoint in the dashboard (Developer → Webhooks) and get the signing secret when you save it. (You can send a test request afterwards to confirm it’s reachable.)
- When an event fires, we POST a JSON payload to your endpoint, signed so you can verify it came from us.
- Your handler verifies the signature (via the SDK) and processes the event.
- You return
2xxto acknowledge. A408,429,5xx, or timeout triggers a retry; any other4xxis treated as a permanent rejection and not retried.
What we send
A single POST with a JSON body, typed as WebhookEvent. One event is delivered:
| Event type | Fires when |
|---|---|
verification.completed | Off-chain verification finishes (success or failure). |
See Event catalog for the full payload.
Ordering and delivery guarantees
- At-least-once. The same event can arrive more than once (a retry after a failed delivery, a network blip). Make your handler idempotent.
- Bounded latency. Typically under a second from verification to delivery. Under retry backoff, latency can grow to minutes.
Idempotency
The event carries a stable ID derived from the verification, so retries of the same event share it:
verification.completed:<verification_id>-completed
Dedupe in your handler on verification_id. See Best practices.
Reliability
Failed deliveries (408, 429, 5xx, timeout, or connection error) are retried automatically on an exponential schedule over a span of days, so a brief outage on your side recovers on its own. Any other 4xx response is a permanent rejection and is not retried, so never return 400 for a transient failure like a database hiccup (see Best practices). Every delivery is signed, see Verify webhooks.
Was this page helpful?
Thanks — what went wrong?
Thanks for your feedback!