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
| Status | When |
|---|---|
succeeded | The video is ready. output.url is signed for this delivery and valid for 60 minutes. |
failed | error says why. The hold is restored. |
canceled | Canceled while queued. The hold is restored. |
Your endpoint
- It must be a public
httpsURL on the default port, with no user name or password in it. - Return any
2xxwithin 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
5xxresponses are retried for up to 2 hours. 3xxand4xxresponses are not retried.- The same event can arrive more than once. Use the
webhook-idheader 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
| Header | Value |
|---|---|
webhook-id | Unique id of the event, the same on every retry. |
webhook-timestamp | Unix time in seconds when this attempt was signed. |
webhook-signature | One or more v1,<base64> signatures separated by spaces. Sent once signing is on. |
content-type | application/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 Falseimport { createHmac, timingSafeEqual } from 'node:crypto';
const SECRET = process.env.SERA_WEBHOOK_SECRET!; // whsec_...
export function verify(headers: Headers, body: string): boolean {
const id = headers.get('webhook-id') ?? '';
const ts = headers.get('webhook-timestamp') ?? '';
if (!ts || Math.abs(Date.now() / 1000 - Number(ts)) > 300) return false;
const key = Buffer.from(SECRET.replace(/^whsec_/, ''), 'base64');
const expected = createHmac('sha256', key).update(`${id}.${ts}.${body}`).digest();
return (headers.get('webhook-signature') ?? '').split(' ').some((part) => {
const [version, sig] = part.split(',');
const got = Buffer.from(sig ?? '', 'base64');
return version === 'v1' && got.length === expected.length && timingSafeEqual(got, expected);
});
}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"
}