Core conceptsWebhooks

Core concepts

Webhooks

Get the finished generation posted to your server instead of polling, and check that it came from Sera Studio.

Send webhook_url when you create a generation. When the generation finishes, Sera Studio sends one POST to that URL. The body is the generation object, the same JSON that Get generation returns.

When a webhook is sent

StatusWhen
succeededThe video is ready. output.url is signed for this delivery and valid for 60 minutes.
failederror says why. The hold is restored.
canceledCanceled while queued. The hold is restored.

Your endpoint

  • It must be a public https URL on the default port, with no user name or password in it.
  • Return any 2xx within 10 seconds, after you have stored the event. Do slow work after you reply.
  • Fields can be added to the body later. Ignore the ones you do not know.

Retries

  • Network errors, timeouts and 5xx responses are retried for up to 2 hours.
  • 3xx and 4xx responses are not retried.
  • The same event can arrive more than once. Use the webhook-id header to skip duplicates; it stays the same across retries.
  • Nothing is sent after the generation's files are deleted.
  • If a webhook never arrives, get the generation or list generations.

Headers

HeaderValue
webhook-idUnique id of the event, the same on every retry.
webhook-timestampUnix time in seconds when this attempt was signed.
webhook-signatureOne or more v1,<base64> signatures separated by spaces. Sent once signing is on.
content-typeapplication/json

Signing secret

Webhooks follow the Standard Webhooks specification. Each workspace has one signing secret, starting with whsec_. An owner or admin creates it the first time they reveal it in the console under Settings (account menu, then Settings). Until then, webhooks are delivered unsigned.

Rotating the secret creates a new one right away. The previous secret keeps signing for 24 hours, so during that time each webhook carries two signatures.

Verify a webhook

Compute HMAC-SHA256 over {webhook-id}.{webhook-timestamp}.{raw body} with the base64-decoded part of the secret after whsec_, base64-encode it, and compare it with each v1, signature in the header. Reject timestamps more than 5 minutes away from your clock, and use the raw request body, not a re-serialized one. Standard Webhooks libraries in many languages do the same check.

import base64, hashlib, hmac, os, time

SECRET = os.environ["SERA_WEBHOOK_SECRET"]  # whsec_...

def verify(headers: dict, body: bytes) -> bool:
    msg_id, ts = headers["webhook-id"], headers["webhook-timestamp"]
    if abs(time.time() - int(ts)) > 300:
        return False
    key = base64.b64decode(SECRET.removeprefix("whsec_"))
    signed = f"{msg_id}.{ts}.".encode() + body
    expected = base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest()).decode()
    for part in headers.get("webhook-signature", "").split():
        version, _, sig = part.partition(",")
        if version == "v1" and hmac.compare_digest(sig, expected):
            return True
    return False

Example body

{
  "id": "0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70",
  "object": "generation",
  "model": "siren",
  "status": "succeeded",
  "created_at": "2026-11-09T05:11:02.000Z",
  "finished_at": "2026-11-09T05:14:40.000Z",
  "input": {
    "source": {
      "upload_id": "vid_3f2c7a9e-5d1b-4c8e-9f20-7a6b5c4d3e21"
    },
    "images": [
      {
        "upload_id": "img_9a0b8c7d-6e5f-4a3b-8c2d-1e0f9a8b7c6d"
      }
    ],
    "prompt": "Keep the motion.",
    "resolution": "720p",
    "source_duration_s": 9.4,
    "webhook_url": "https://example.com/hooks/sera"
  },
  "progress": null,
  "output": {
    "url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70/a1/master.mp4?token=<signed>",
    "thumbnail_url": "https://rvzzbovxmjgldcnlbwyx.supabase.co/storage/v1/object/sign/episodes/7d9e2f10-4b3a-4c5d-8e6f-0a1b2c3d4e5f/episodes/0b6e2c1a-7c1a-4f5e-9a51-2b3c4d5e6f70/a1/thumb.jpg?token=<signed>",
    "duration_s": 9.4,
    "url_expires_at": "2026-11-09T06:15:00.000Z",
    "retained_until": "2026-11-16T05:14:40.000Z"
  },
  "output_deleted": false,
  "error": null,
  "billing": {
    "currency": "usd",
    "resolution": "720p",
    "usd_per_second": 0.175,
    "discount_pct": 0,
    "held_usd": 3.5,
    "charged_usd": 3.5,
    "restored_usd": 0,
    "settled": true
  },
  "idempotency_key": "order-1182"
}