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

# Configuring endpoints

> Create, update, enable, disable, and rotate webhook endpoints.

A webhook endpoint is the URL Kayle delivers events to. You can manage endpoints from the dashboard or via the API. The signing secret returned at creation is what your server uses to verify incoming deliveries.

## Create an endpoint

```bash theme={null}
curl -X POST https://api.kayle.id/v1/webhooks/endpoints \
  -H "Authorization: Bearer kk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Production webhook",
    "url": "https://yourapp.com/webhooks/kayle",
    "undelivered_payload_retention_hours": 72,
    "subscribed_event_types": [
      "verification.session.succeeded",
      "verification.session.failed"
    ]
  }'
```

The response includes the endpoint and its signing secret. Note that the endpoint cannot receive deliveries until you also register an [encryption key](/webhooks/encryption).

```json theme={null}
{
  "data": {
    "endpoint": {
      "id": "whe_...",
      "organization_id": "...",
      "name": "Production webhook",
      "url": "https://yourapp.com/webhooks/kayle",
      "enabled": true,
      "subscribed_event_types": [
        "verification.session.succeeded",
        "verification.session.failed"
      ],
      "undelivered_payload_retention_hours": 72,
      "created_at": "2026-05-05T11:00:00Z",
      "updated_at": "2026-05-05T11:00:00Z",
      "disabled_at": null
    },
    "signing_secret": "whsec_..."
  },
  "error": null
}
```

<Warning>
  The signing secret is shown **once** at creation. Store it in your secret manager immediately. If you lose it, rotate via `POST /v1/webhooks/endpoints/:endpoint_id/signing-secret/rotate`.
</Warning>

`url` must be `https://`. The `name` field is optional and is only used in the dashboard for display.

## Update an endpoint

`PATCH /v1/webhooks/endpoints/:endpoint_id` accepts any subset of `name`, `url`, `enabled`, `subscribed_event_types`, and `undelivered_payload_retention_hours`. To temporarily stop deliveries without losing the configuration, set `enabled: false` — disabled endpoints retain history and can be re-enabled later.

## Undelivered payload retention

Delivered webhook payloads are scrubbed immediately after the first successful `2xx` response. The `undelivered_payload_retention_hours` setting only controls how long Kayle keeps encrypted payloads after a delivery exhausts automatic retries and becomes `failed`.

Supported values are `0`, `24`, `72`, and `168` hours. New endpoints default to `72`. Use `0` if you do not want manual retry or replay after final delivery failure; use a longer window if your downstream service may need time to recover from an outage.

## Reveal or rotate the signing secret

Reveal the current secret (admin-only, owner role required):

```bash theme={null}
curl -X POST https://api.kayle.id/v1/webhooks/endpoints/whe_.../signing-secret/reveal \
  -H "Authorization: Bearer kk_..."
```

Rotate to a new secret:

```bash theme={null}
curl -X POST https://api.kayle.id/v1/webhooks/endpoints/whe_.../signing-secret/rotate \
  -H "Authorization: Bearer kk_..."
```

After rotation the previous secret stops working immediately. If you can't deploy the new secret atomically, expect a window where in-flight deliveries fail signature verification on your side — Kayle will retry them with the new secret, so the deliveries eventually succeed once your server has the rotated value.

## Delete an endpoint

```bash theme={null}
curl -X DELETE https://api.kayle.id/v1/webhooks/endpoints/whe_... \
  -H "Authorization: Bearer kk_..."
```

Deletion is permanent. In-flight retries against the deleted endpoint stop. Past delivery rows remain in the database for audit but no longer deliver.

## Encryption keys

Webhook payloads are always JWE-encrypted. A new endpoint cannot receive deliveries until you register an active encryption key on it — the API will record a `failed` delivery row instead of sending the body. Register a key immediately after creation. See [Encrypted payloads](/webhooks/encryption) for the registration flow and decryption guidance.

## Permissions

Managing endpoints requires `webhooks:write` on an API key, or the `admin` / `owner` role on a session-cookie caller. Reading lists endpoints requires `webhooks:read` or any role. See [Scopes](/auth/scopes) for the full mapping.