Webhook payloads and signature verification

Two ids appear, and they are not interchangeable. batch_id is the id POST /v1 answered with, and the one GET /v1/{job_id} accepts. job_id in a job event identifies a single video inside it; reading it as a job returns 404.

Every delivery carries X-TubeExtract-Signature, an HMAC-SHA256 of the raw body using the endpoint’s signing secret, and X-TubeExtract-Timestamp in Unix seconds. The signed string is {timestamp}.{body}, so a captured body cannot be replayed later under a new timestamp. Compare with a constant-time function and reject anything older than five minutes.

import crypto from "node:crypto";
 
export function verify(rawBody, headers, secret) {
  const timestamp = headers["x-tubeextract-timestamp"];
  const signature = headers["x-tubeextract-signature"];
 
  // Anything older than five minutes is a replay, not a delivery.
  if (Math.abs(Date.now() / 1000 - Number(timestamp)) > 300) return false;
 
  const expected =
    "v1=" +
    crypto
      .createHmac("sha256", secret)
      .update(`${timestamp}.${rawBody}`)
      .digest("hex");
 
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}

Each endpoint has its own secret, shown on the webhooks screen. Rotating it there keeps the previous one valid for 24 hours, so a deploy has time to catch up.

Deliveries also carry a Web Bot Auth signature (an RFC 9421 HTTP message signature in the Signature, Signature-Input and Signature-Agent headers), which lets a firewall or CDN that supports it, Cloudflare included, confirm a request really came from TubeExtract without knowing your endpoint’s secret. The public key is at /.well-known/http-message-signatures-directory. The HMAC above is still what verifies a payload is intact and meant for your endpoint.

Anything other than a 2xx is retried. A delivery gets five attempts in all: immediately, then 30 seconds, 2 minutes, 10 minutes and 30 minutes after each failure, about 45 minutes end to end. Each delivery, with its attempt count and last response code, is listed on the webhooks screen, where a failed delivery can be replayed by hand without re-running the extraction.