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

# Webhooks overview

> Subscribe to render-job lifecycle events. HMAC-signed, retried with exponential backoff, replayable from the DLQ.

Webhooks let your backend react to events Kynva produces — render completions, failures, carousel batch finishes — without polling.

## The flow

```
Render queued     ─►  Kynva renders   ─►  POST your endpoint
                                          (HMAC-signed, JSON body)
                       │
                       ├── 2xx in 30s   → delivered
                       └── otherwise    → retried 0, 1m, 5m, 30m, 2h
                                          → finally → DLQ
```

## Quick start

<Steps>
  <Step title="Create a webhook">
    ```bash theme={null}
    curl -X POST https://api.kynva.ai/api/v1/facade/webhooks \
      -H "Authorization: Bearer $KYNVA_API_KEY" \
      -H "Content-Type: application/json" \
      -H "Idempotency-Key: $(uuidgen)" \
      -d '{
        "url": "https://your-app.com/webhooks/kynva",
        "events": ["render.completed", "render.failed"],
        "description": "Production render events"
      }'
    ```

    The response includes the **secret** (`whsec_...`) — store it. You'll never see it again.
  </Step>

  <Step title="Verify the signature">
    Every delivery includes `X-RenderForge-Signature: sha256=<hex>`. Verify before trusting the payload. See [verification examples](/webhooks/verification-examples).
  </Step>

  <Step title="Respond fast">
    Return `2xx` within **30 seconds**. Anything else is a delivery failure and gets retried.
  </Step>
</Steps>

## Delivery headers

Every webhook POST to your endpoint includes:

| Header                    | Notes                                                                 |
| ------------------------- | --------------------------------------------------------------------- |
| `Content-Type`            | `application/json`                                                    |
| `X-RenderForge-Signature` | `sha256=<hex>` HMAC-SHA256 of the raw body using your webhook secret. |
| `X-RenderForge-Event`     | The event type (e.g. `render.completed`).                             |
| `X-RenderForge-Delivery`  | Unique delivery ID. Use this for idempotent processing on your end.   |
| `X-RenderForge-Timestamp` | ISO 8601 timestamp at delivery time.                                  |

## Delivery contract

| Behavior           | Detail                                                                                                   |
| ------------------ | -------------------------------------------------------------------------------------------------------- |
| **Timeout**        | 30s. Anything slower counts as a failure.                                                                |
| **Retry policy**   | 5 attempts at delays `0, 1m, 5m, 30m, 2h`. After the last, the event lands in the DLQ.                   |
| **Success**        | Any `2xx` response.                                                                                      |
| **Server failure** | Any `5xx`, timeout, or network error → schedules a retry.                                                |
| **Client failure** | `4xx` (except `429`) → no retry. Likely a permanent misconfiguration on your end.                        |
| **Ordering**       | Best-effort, not guaranteed. Use `X-RenderForge-Timestamp` and your business logic if you need ordering. |
| **At-least-once**  | A retry after partial success may deliver the same event again. Dedupe on `X-RenderForge-Delivery`.      |

## Dead-letter queue (DLQ)

Events that fail all retries are kept for **14 days** in the DLQ. You can:

* List them: `GET /api/v1/facade/webhooks/dlq`
* Replay one: `POST /api/v1/facade/webhooks/dlq/{event_id}/retry`

This is the safety net for outages on your side.

## Next

<CardGroup cols={2}>
  <Card title="Verify signatures" icon="signature" href="/webhooks/verification-examples">
    Constant-time HMAC verification in TS, Python, and a curl test.
  </Card>

  <Card title="All event types" icon="bolt" href="/webhooks/events">
    Payload schemas for every event.
  </Card>

  <Card title="Security model" icon="shield-halved" href="/webhooks/security">
    Signing, secret rotation, replay protection.
  </Card>

  <Card title="Manage webhooks" icon="webhook" href="/api-reference/webhooks/list">
    The CRUD endpoints in the API reference.
  </Card>
</CardGroup>