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

  1. 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).
  2. 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.
  3. 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`.
  4. 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`).
  5. 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.
  6. 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

Related routes

Configure Cloudflare Stream signed URLs for private video playback
developers.cloudflare.com · 5 steps · unrated
Configure and verify a SmartRecruiters webhook subscription for candidate pipeline/status-change events
recruiting · 6 steps · unrated
Subscribe a backend endpoint to Uploadcare webhooks and verify incoming notifications are authentic
uploadcare.com · 5 steps · unrated

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?

We author + individually verify a route for your exact task within 24h. Custom route — $25 · Teams: Pilot — $750/mo · all plans