Skip to main content

Webhooks

A webhook is a URL of yours that Crumbcast sends a POST to when something happens to the project's videos and live streams: no need to keep asking whether a video is ready. Add them in the project's Settings → Webhooks, or with an admin token through Create Webhook. Each has its own secret (whsec_…) and the events it takes: all of them, or the ones you pick.

A project's webhooks in its settings

URLs must be https, on a public address.

What's sent​

A JSON body:

{
"id": "5b0e…",
"type": "video.ready",
"created_at": "2026-10-24T09:12:03.418Z",
"project_id": "01a1…",
"data": { "video": { "id": "3f2b9c1e-…", "metadata": { "customer_id": "c-42" }, "…": "…" } }
}

A video's events carry its metadata, the pairs you gave it, so you can match the event to your own records directly.

and these headers:

Header
Crumbcast-EventThe event's type
Crumbcast-DeliveryThis delivery's ID (a new one each time it's sent)
Crumbcast-Signaturet=<unix time>,v1=<signature>

Check the signature​

v1 is the hex HMAC-SHA256, with the webhook's secret, of <t>.<body>. Check it over the body's bytes exactly as they came (before parsing the JSON), and that t is recent, before trusting a delivery:

import hashlib
import hmac
import time


def verified(secret: str, header: str, body: bytes, tolerance: int = 300) -> bool:
parts = dict(part.split("=", 1) for part in header.split(","))
expected = hmac.new(secret.encode(), f"{parts['t']}.".encode() + body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, parts["v1"]) and abs(time.time() - int(parts["t"])) <= tolerance
import crypto from "node:crypto";

const verified = (secret, header, body, tolerance = 300) => {
const { t, v1 } = Object.fromEntries(header.split(",").map((part) => part.split("=")));
const expected = crypto.createHmac("sha256", secret).update(`${t}.${body}`).digest("hex");
return (
v1.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected)) &&
Math.abs(Date.now() / 1000 - Number(t)) <= tolerance
);
};

The SDKs check it for you, and answer with the event, typed by its type:

import { verifyWebhook } from "crumbcast";

const event = await verifyWebhook(body, request.headers.get("Crumbcast-Signature"), secret);

Each throws a WebhookVerificationError (PHP's: WebhookVerificationException) for a delivery that isn't the webhook's or is too old; answer it 400. A whole handler for Next.js, Express, FastAPI, Flask, Django, Laravel and Symfony is in the JavaScript, Python and PHP SDKs' pages.

Answer quickly​

Answer with a 2xx within 10 seconds; do the work afterwards. Anything else, a redirect too, is tried again after 1 min, 5 min, 30 min, 2 h, 5 h, 10 h and 24 h, then given up.

Deliveries may come more than once and out of order. Use the event's id to skip one you've already handled, and created_at (or the state of the video in it) rather than the order they arrive in.

Events​

TypeWhendata
video.createdA video comes into the project: an upload started, an import, a clip, a recordingvideo
video.readyIt plays: a format became playable while none wasvideo
video.encodedNothing of it is encoding any more: each format completed or failedvideo, failed
video.format.readyA format finished encodingvideo, format
video.format.erroredA format couldn't be encodedvideo, format
video.erroredIts file couldn't be made (an import, clip or recording); it's deleted nextvideo, reason
video.trashedIt was deleted into the project's trash, where it can be restoredvideo
video.restoredIt was restored from the trash, as it wasvideo
video.deletedIt was deleted for good (as it was just before)video
video.captions.readyCaptions made from its speech are readyvideo, caption
video.captions.erroredThey couldn't be madevideo, caption
live_stream.activeA broadcast plays for its viewerslive_stream, broadcast
live_stream.disconnectedIts encoder stopped sending: it waits for it to come backlive_stream, broadcast
live_stream.reconnectedIts encoder came back in timelive_stream, broadcast
live_stream.idleThe broadcast ended (broadcast.recording_id: the video it's recorded into)live_stream, broadcast
webhook.testSent from the webhook's menu, to it alonewebhook_id

When something goes wrong​

Each webhook's deliveries of the last 30 days, with the answer your server gave, are in its settings and under List Webhook Deliveries, to see what went wrong.

  • Send Again sends a delivery's event once more, as a new delivery with the same event id: once your server is fixed, catch up on what it missed.
  • Send Test sends a webhook.test to the webhook alone, whatever events it takes. It must be on (enabled).
  • Roll Webhook Secret gives it a new secret, if the old one leaked. Every delivery is signed with the new one from then on, including those still waiting to be tried again: give your server the new one straight away.
  • Update Webhook changes its URL and events, or turns it off ("enabled": false) without deleting it.