Filmsquare HelpDocs

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.

Updated 4 min read.md

On this page
  1. Subscribe
  2. Events
  3. The delivery
  4. The data of each event
  5. Check the signature
  6. Answer and retries
  7. When a subscription is switched off
  8. Related

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_…"}
  • events is a list of event types, or ["*"] for all of them.
  • url must be an http or https address 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 409 with the code webhook_limit.
RouteDoes
GET /workspaces/{ws}/webhooksList subscriptions (without secrets)
POST /workspaces/{ws}/webhooksSubscribe; 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 #

TypeSent when
generation.succeededA take finished rendering
generation.failedA render failed (also when Filmsquare retries it on its own)
take.selectedA take was picked on a shot or scene
asset_version.createdA 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": ["…"]}}
HeaderValue
x-fs-signaturesha256= + the hex HMAC-SHA256 of the raw body, keyed with your secret
x-fs-eventThe event type
x-fs-deliveryThe event id. The same event always has the same id

The data of each event #

Typedata fields
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (the automatic next attempt, or null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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 answerWhat Filmsquare does
2xxDone
5xx, 429, a timeout or a network errorTries again after about 10 seconds, 1 minute and 5 minutes, up to 4 attempts
410Switches the subscription off at once
Any other 4xxGives 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:

FieldValue
consecutive_failuresFailed tries in a row
consecutive_slowThe slow count: up 1 for each answer slower than 5 seconds, down 1 for each faster one
failing_sinceWhen the current run of failures began, or null
disabled_atWhen it was switched off, or null
disabled_reasonWhy 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.

This page as Markdown: /docs/api/webhooks.md