6.0 API6.2 Webhooks
Webhooks
Subscribe a URL to Filmsquare events, the four event types and their payloads, how deliveries are signed with x-fs-signature, and how retries work.
A webhook sends an event to your URL when something happens in a workspace: a take finished or failed, a take was picked, a new version came in. Use it instead of polling.
Webhooks are managed through the API by a producer or owner. There is no screen for them in the studio, and your Claude cannot reach them (they send data out of Filmsquare).
Subscribe #
curl -s -X POST "$FS/workspaces/$WS/webhooks" \
-H "Authorization: Bearer $FS_KEY" -H "content-type: application/json" \
-d '{"url": "https://example.com/filmsquare/hook", "events": ["generation.succeeded", "take.selected"]}'
{"id": "…", "workspace_id": "…", "url": "https://example.com/filmsquare/hook",
"events": ["generation.succeeded", "take.selected"], "active": true,
"created_by": "…", "created_at": "2026-10-26T10:12:03.000Z",
"secret": "whsec_…"}
eventsis a list of event types, or["*"]for all of them.urlmust be anhttporhttpsaddress on a public host, without a user name or password in it.- A workspace can have at most 10 active subscriptions. The 11th one, or switching one on past 10, answers
409with the codewebhook_limit.
| Route | Does |
|---|---|
GET /workspaces/{ws}/webhooks | List subscriptions (without secrets) |
POST /workspaces/{ws}/webhooks | Subscribe; returns the secret once |
PATCH /workspaces/{ws}/webhooks/{id} | Change url, events or active |
DELETE /workspaces/{ws}/webhooks/{id} | Stop deliveries (the subscription is deactivated, not deleted) |
All four need the producer role or higher.
Events #
| Type | Sent when |
|---|---|
generation.succeeded | A take finished rendering |
generation.failed | A render failed (also when Filmsquare retries it on its own) |
take.selected | A take was picked on a shot or scene |
asset_version.created | A render produced a new asset version |
Events about takes in a person's private sketchbook (Create) are never sent.
The delivery #
Each delivery is a POST to your URL with the event as its JSON body:
POST /filmsquare/hook HTTP/1.1
content-type: application/json
x-fs-signature: sha256=5d1c…
x-fs-event: generation.succeeded
x-fs-delivery: generation.succeeded:9b2e…
{"id": "generation.succeeded:9b2e…", "type": "generation.succeeded",
"workspaceId": "…", "createdAt": "2026-10-26T10:14:51.220Z",
"data": {"generationId": "9b2e…", "takeId": "…", "shotId": "…", "sceneId": null, "elementId": null,
"kind": "video", "tier": "draft", "provider": "byteplus", "modelKey": "…",
"costCredits": 22.7, "assetVersionIds": ["…"]}}
| Header | Value |
|---|---|
x-fs-signature | sha256= + the hex HMAC-SHA256 of the raw body, keyed with your secret |
x-fs-event | The event type |
x-fs-delivery | The event id. The same event always has the same id |
The data of each event #
| Type | data fields |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId (the automatic next attempt, or null) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, takeId, generationId, mime |
Fetch the file of an asset version with GET /workspaces/{ws}/asset-versions/{id}/url (a signed download URL).
Check the signature #
Compute the HMAC over the raw request body, exactly as received, before you parse it. The key is the whole secret,
whsec_ included. Compare in constant time.
import { createHmac, timingSafeEqual } from "node:crypto";
export function isFromFilmsquare(secret, rawBody, header) {
if (!header) return false;
const want = "sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex");
return want.length === header.length && timingSafeEqual(Buffer.from(want), Buffer.from(header));
}
Reject a delivery whose signature does not match.
Answer and retries #
Answer with any 2xx status, quickly. Do slow work after you answer. Filmsquare waits at most 10 seconds for your answer; a slower
answer counts as a failed try.
| Your answer | What Filmsquare does |
|---|---|
2xx | Done |
5xx, 429, a timeout or a network error | Tries again after about 10 seconds, 1 minute and 5 minutes, up to 4 attempts |
410 | Switches the subscription off at once |
Any other 4xx | Gives up on this delivery |
A delivery can arrive more than once, and events can arrive out of order. Use x-fs-delivery to skip events you
already handled, and createdAt to order them.
If more than 500 deliveries are waiting for one workspace, new events for it are not queued.
When a subscription is switched off #
Every try that does not get a 2xx counts as a failure: a timeout, a network error or any other status. A 2xx sets
the count back to 0. Filmsquare switches the subscription off (active becomes false) when:
- 5 or more tries in a row failed, and the first of them was at least 10 minutes ago, or
- your URL answered
410, or - your URL is slow more often than not. Each answer that takes longer than 5 seconds, even a
2xx, adds 1 to a slow count, and each faster answer takes 1 off (never below 0). At 20 the subscription is switched off. A timeout or a network error counts only as a failed try, never as slow.
A short outage, such as a deploy, does not switch it off. Deliveries still waiting for a switched-off subscription are not sent, and the owners of the workspace get a notification in their inbox, at most once a day per subscription. The subscription shows why:
| Field | Value |
|---|---|
consecutive_failures | Failed tries in a row |
consecutive_slow | The slow count: up 1 for each answer slower than 5 seconds, down 1 for each faster one |
failing_since | When the current run of failures began, or null |
disabled_at | When it was switched off, or null |
disabled_reason | Why it was switched off, or null |
To switch it on again, update the webhook with "active": true. That sets consecutive_failures and
consecutive_slow back to 0 and clears the reason. A subscription that switched itself off can be switched on again
3 times in 24 hours. After that the update answers 409 with the code webhook_rearm_limit: fix your endpoint
first.