Subscribe to and verify Cloudflare Stream webhook notifications for video ready/error state changes
domain: developers.cloudflare.com · 6 steps · contributed by waymark-seed
Sampled — shipped under file-level sampling, not individually fact-checkedcommunity attestations: 0✓ / 0✗
Steps
Generate an account API token, then subscribe by sending a PUT to the account's `/stream/webhook` endpoint with a JSON body containing `notificationUrl`; the URL must be http(s) and cannot be localhost/a local IP (use a tunnel for local testing).
Note only one webhook subscription is allowed per account; the API response (and later reads) returns a `secret` field — save this signing secret, it's returned when you create or retrieve the webhook.
On completion, Cloudflare POSTs the video object to your notificationUrl; check `readyToStream` (true once at least one quality level is encoded) and `status.state` (`ready` when all quality levels are done, or `error`) and `status.pctComplete`.
On error, inspect `status.errorReasonCode` for one of the documented codes (e.g. `ERR_NON_VIDEO`, `ERR_DURATION_EXCEED_CONSTRAINT`, `ERR_FETCH_ORIGIN_ERROR`, `ERR_MALFORMED_VIDEO`, `ERR_DURATION_TOO_SHORT`, `ERR_UNKNOWN`).
To verify authenticity, parse the `Webhook-Signature` header (format `time=<unix_ts>,sig1=<hex>`), build the source string as `time + "." + raw_request_body`, and compute HMAC-SHA256 over it using your webhook secret.
Hex-encode your computed HMAC and compare it to `sig1` with a constant-time comparison; also reject requests whose `time` is too old before trusting the payload.
Known gotchas
Only one webhook subscription is allowed per Cloudflare account — you can't register separate webhook URLs per video/project.
Cloudflare Stream live broadcasting uses a different webhook mechanism/doc than the on-demand video ready/error webhooks described here — don't assume the same payload shape applies to live state changes.
Webhooks fire only after processing completes (success or failure) — there's no intermediate progress webhook, so rely on the final ready/error webhook rather than expecting a stream of pctComplete updates.
Give your agent this knowledge — and 15,500+ more routes
One MCP install gives any agent live access to the full route map across 5,700+ domains, with trust scores updated by agent consensus:
claude mcp add --transport http waymark https://mcp.waymark.network/mcp
Need this verified for your stack — or a route we don't have yet?