Webhooks

This guide shows you how to create a webhook endpoint, verify a delivery signature, and inspect or redeliver past events.

Webhooks send event notifications to a public HTTPS endpoint. MANAGE_WEBHOOKS controls endpoint and delivery operations.

Event Vocabulary

The closed event set is:

Every event uses the same envelope:

{
  "id": "evt_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
  "type": "run.completed",
  "created_at": "2026-08-08T10:05:00.000Z",
  "data": {
    "run_id": "run_0190b5d4-7e1f-7a2b-9c3d-1234567890ab",
    "status": "completed"
  }
}

The event-specific data object uses snake_case. Use GET /api/v1alpha1/runs/{run_id} to read the authoritative result.

Create An Endpoint

curl --fail-with-body -X POST "$BASE_URL/api/v1alpha1/webhooks" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: webhook-create-01" \
  -d '{
    "url": "https://hooks.example.com/deepframe",
    "description": "Review event receiver",
    "events": ["video.indexed", "run.completed"]
  }'

The create response returns the endpoint id and signing secret once. Store it securely. The secret is not returned by list, get, or update operations. Endpoint URLs must be public HTTPS destinations and pass the API SSRF policy.

New webhooks are enabled by default; enabled is not accepted on create but appears in the response, and you can toggle it later with PATCH /api/v1alpha1/webhooks/{webhook_id}.

Verify A Delivery

Standard Webhooks deliveries use the endpoint secret with these headers:

• webhook-id
• webhook-timestamp
• webhook-signature

Verify the raw request body, timestamp tolerance, and signature before parsing JSON. Reject stale timestamps and replayed event ids according to your receiver policy.

Delivery History And Redelivery

List delivery history:

curl --fail-with-body "$BASE_URL/api/v1alpha1/webhooks/$WEBHOOK_ID/deliveries" \
  -H "Authorization: Bearer $DEEPFRAME_API_KEY"

Request a redelivery with POST /api/v1alpha1/webhooks/{webhook_id}/deliveries/{delivery_id}/redeliver and an Idempotency-Key. A redelivery is asynchronous; inspect the delivery record for its status and attempt count.