Webhooks

# Webhooks **Developer → Webhooks**. Register the HTTPS endpoints Self posts events to. For the delivery model, signatures, retries, and payloads, see the [Webhooks section](/docs/self-enterprise/webhooks/overview/). ![Webhooks settings](/docs/docs-assets/webhook.avif) ## Add an endpoint First pick the environment with the **Test | Live** tab strip at the top of the page; the endpoint you create is stamped with the selected environment. Then click **Add webhook** and fill in: - **Webhook URL** (required): the **full** public HTTPS URL including your handler's path, e.g. `https://yourapp.com/webhooks/self`, not just the domain. - **Name** (optional): a label for the endpoint. Two rules are enforced when you save, in the dashboard and equally on the API, so you can't bypass them by calling directly: - **`https://` only.** Endpoints receive signed proof payloads; plain `http://` is rejected. - **A publicly reachable host.** Private, loopback, link-local and other reserved addresses are rejected, as are internal hostnames like `localhost`. To develop against a machine you can't expose, put a tunnel (ngrok, Cloudflare Tunnel, or similar) in front of it and register the public URL. :::warning Always include the path. If you register a bare domain (`https://yourapp.com`), deliveries often land on your web app's page route instead of your webhook handler, where they're silently swallowed. ::: Click **Save**. The endpoint is saved right away and the **signing secret** (`whsec_...`) is revealed **once** in a banner. This is the only time you'll see it, copy it into your secret manager as `SELF_WEBHOOK_SECRET`. Every endpoint receives the `verification.completed` event; there's no per-endpoint event picker. Branch on `event.type` in your handler. See the [event catalog](/docs/self-enterprise/webhooks/events/). ## Verify the signature Once you have the `whsec_...` secret, wire up real signature verification so you only act on genuine events. See [Verify webhooks](/docs/self-enterprise/webhooks/verify-webhooks/). ## Send a test request A saved endpoint has a **Send Test Request** button. It delivers a sample event to your URL and reports whether the endpoint accepted it (returned `2xx`). When it doesn't, the dialog shows the **status code your endpoint returned and the start of its response body**, which is usually enough to tell a wrong path from a crashing handler. It's repeatable, use it to confirm your handler is reachable and responding before you rely on live traffic. Sending a test is optional and never required to save an endpoint. :::note A live endpoint is a **prerequisite for [Custom Config](/docs/self-enterprise/workspaces/custom-config/)**: those flows deliver results only to your webhook (Self stores nothing), so Deploy is disabled and live `sessions.create(...)` returns `409 no_webhook_endpoint` until one exists here. Deleting your last live endpoint puts deployed Custom Configs back in that blocked state. ::: ## Related - [Webhooks: overview](/docs/self-enterprise/webhooks/overview/): delivery, retries, and idempotency. - [Verify webhooks](/docs/self-enterprise/webhooks/verify-webhooks/): how to validate a delivery. - [Event catalog](/docs/self-enterprise/webhooks/events/): every event and its payload.

On this page

Add an endpoint
Verify the signature
Send a test request
Related

Developer → Webhooks. Register the HTTPS endpoints Self posts events to. For the delivery model, signatures, retries, and payloads, see the Webhooks section.

Webhooks settings

Add an endpoint

First pick the environment with the Test | Live tab strip at the top of the page; the endpoint you create is stamped with the selected environment. Then click Add webhook and fill in:

Webhook URL (required): the full public HTTPS URL including your handler’s path, e.g. https://yourapp.com/webhooks/self, not just the domain.
Name (optional): a label for the endpoint.

Two rules are enforced when you save, in the dashboard and equally on the API, so you can’t bypass them by calling directly:

https:// only. Endpoints receive signed proof payloads; plain http:// is rejected.
A publicly reachable host. Private, loopback, link-local and other reserved addresses are rejected, as are internal hostnames like localhost. To develop against a machine you can’t expose, put a tunnel (ngrok, Cloudflare Tunnel, or similar) in front of it and register the public URL.

Click Save. The endpoint is saved right away and the signing secret (whsec_...) is revealed once in a banner. This is the only time you’ll see it, copy it into your secret manager as SELF_WEBHOOK_SECRET.

Every endpoint receives the verification.completed event; there’s no per-endpoint event picker. Branch on event.type in your handler. See the event catalog.

Verify the signature

Once you have the whsec_... secret, wire up real signature verification so you only act on genuine events. See Verify webhooks.

Send a test request

A saved endpoint has a Send Test Request button. It delivers a sample event to your URL and reports whether the endpoint accepted it (returned 2xx). When it doesn’t, the dialog shows the status code your endpoint returned and the start of its response body, which is usually enough to tell a wrong path from a crashing handler. It’s repeatable, use it to confirm your handler is reachable and responding before you rely on live traffic. Sending a test is optional and never required to save an endpoint.

Webhooks: overview: delivery, retries, and idempotency.
Verify webhooks: how to validate a delivery.
Event catalog: every event and its payload.

Was this page helpful?