Webhooks overview

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

Create a webhook

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.

Verify the signature

Every delivery includes X-RenderForge-Signature: sha256=<hex>. Verify before trusting the payload. See verification examples.

Respond fast

Return 2xx within 30 seconds. Anything else is a delivery failure and gets retried.

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.

Verify signatures

Constant-time HMAC verification in TS, Python, and a curl test.

All event types

Payload schemas for every event.

Security model

Signing, secret rotation, replay protection.

Manage webhooks

The CRUD endpoints in the API reference.

​The flow

​Quick start

​Delivery headers

​Delivery contract

​Dead-letter queue (DLQ)

​Next