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

# Webhooks

> Subscribe to job lifecycle events with HMAC-signed, retry-guaranteed delivery.

## How webhooks work

Register an HTTPS endpoint and Framelane will `POST` a signed JSON payload whenever a job event occurs.

```
Framelane  →  POST your-endpoint  →  200 OK  ✓
                                   →  non-2xx  →  retry schedule
```

Each webhook delivery is a new HTTP POST with a signed body. Your endpoint must respond with `2xx` within **10 seconds** or the delivery is marked failed and queued for retry.

## Registering a webhook

```bash theme={null}
curl -X POST https://api.framelane.io/v1/webhooks \
  -H "Authorization: Bearer $FRAMELANE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/hooks/framelane",
    "events": ["render.completed", "render.failed", "task.completed"]
  }'
```

**Response** — includes your workspace signing secret:

```json theme={null}
{
  "id": "wh_01J...",
  "url": "https://yourapp.com/hooks/framelane",
  "events": ["render.completed", "render.failed", "task.completed"],
  "enabled": true,
  "secret": "whsec_..."
}
```

Store the `secret` securely — it's used to [verify signatures](/webhooks/signature-verification). This is your workspace-level signing secret, so the same value is returned for every webhook you create, and rotating it re-keys them all.

## Per-request webhooks

You can override workspace webhooks for a single job by including `webhook_url` in the request body:

```json theme={null}
{
  "source_url": "...",
  "webhook_url": "https://yourapp.com/hooks/framelane?job_ref=123"
}
```

## Endpoints

| Method   | Path                                       | Description                          |
| -------- | ------------------------------------------ | ------------------------------------ |
| `POST`   | `/v1/webhooks`                             | Register a webhook endpoint          |
| `GET`    | `/v1/webhooks`                             | List all webhook endpoints           |
| `GET`    | `/v1/webhooks/{id}`                        | Get a webhook                        |
| `PATCH`  | `/v1/webhooks/{id}`                        | Update URL, events, or enabled state |
| `DELETE` | `/v1/webhooks/{id}`                        | Delete a webhook                     |
| `POST`   | `/v1/webhooks/{id}/test`                   | Send a `webhook.test` event          |
| `POST`   | `/v1/webhooks/{id}/rotate-secret`          | Rotate the signing secret            |
| `GET`    | `/v1/webhooks/{id}/deliveries`             | List delivery attempts               |
| `POST`   | `/v1/webhooks/{id}/deliveries/{did}/retry` | Manually retry a delivery            |