---
title: "Webhooks"
description: "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."
url: https://www.filmsquare.ai/docs/api/webhooks/
lang: en
section: api
updated: 2026-11-17
---

# Webhooks

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

```bash
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"]}'
```

```json
{"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_…"}
```

> [!NOTE]
> The `secret` is returned only here. Store it: you need it to check every delivery.

- `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`.

| 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:

```http
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.

```js
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.

## Related

- [API overview and keys](https://www.filmsquare.ai/docs/api/overview/)
- [OpenAPI reference](https://www.filmsquare.ai/docs/api/openapi/)
