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.

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-Event | The event's type |
Crumbcast-Delivery | This delivery's ID (a new one each time it's sent) |
Crumbcast-Signature | t=<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:
- JavaScript
- Python
- PHP
import { verifyWebhook } from "crumbcast";
const event = await verifyWebhook(body, request.headers.get("Crumbcast-Signature"), secret);
from crumbcast import verify_webhook
event = verify_webhook(body, request.headers.get("Crumbcast-Signature"), secret)
use Crumbcast\Webhook;
$event = Webhook::verify($body, $_SERVER['HTTP_CRUMBCAST_SIGNATURE'] ?? null, $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
| Type | When | data |
|---|---|---|
video.created | A video comes into the project: an upload started, an import, a clip, a recording | video |
video.ready | It plays: a format became playable while none was | video |
video.encoded | Nothing of it is encoding any more: each format completed or failed | video, failed |
video.format.ready | A format finished encoding | video, format |
video.format.errored | A format couldn't be encoded | video, format |
video.errored | Its file couldn't be made (an import, clip or recording); it's deleted next | video, reason |
video.trashed | It was deleted into the project's trash, where it can be restored | video |
video.restored | It was restored from the trash, as it was | video |
video.deleted | It was deleted for good (as it was just before) | video |
video.captions.ready | Captions made from its speech are ready | video, caption |
video.captions.errored | They couldn't be made | video, caption |
live_stream.active | A broadcast plays for its viewers | live_stream, broadcast |
live_stream.disconnected | Its encoder stopped sending: it waits for it to come back | live_stream, broadcast |
live_stream.reconnected | Its encoder came back in time | live_stream, broadcast |
live_stream.idle | The broadcast ended (broadcast.recording_id: the video it's recorded into) | live_stream, broadcast |
webhook.test | Sent from the webhook's menu, to it alone | webhook_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.testto 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.