Skip to main content
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

1

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.
2

Verify the signature

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

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:
HeaderNotes
Content-Typeapplication/json
X-RenderForge-Signaturesha256=<hex> HMAC-SHA256 of the raw body using your webhook secret.
X-RenderForge-EventThe event type (e.g. render.completed).
X-RenderForge-DeliveryUnique delivery ID. Use this for idempotent processing on your end.
X-RenderForge-TimestampISO 8601 timestamp at delivery time.

​
Delivery contract

BehaviorDetail
Timeout30s. Anything slower counts as a failure.
Retry policy5 attempts at delays 0, 1m, 5m, 30m, 2h. After the last, the event lands in the DLQ.
SuccessAny 2xx response.
Server failureAny 5xx, timeout, or network error → schedules a retry.
Client failure4xx (except 429) → no retry. Likely a permanent misconfiguration on your end.
OrderingBest-effort, not guaranteed. Use X-RenderForge-Timestamp and your business logic if you need ordering.
At-least-onceA 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

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.