6.0 API6.2 Webhooks
Webhooks
Abonniere eine URL auf Filmsquare-Events, die vier Event-Typen und ihre Payloads, wie Zustellungen mit x-fs-signature signiert werden, und wie Wiederholungen funktionieren.
Ein Webhook schickt ein Event an deine URL, wenn in einem Workspace etwas passiert: Ein Take ist fertig oder fehlgeschlagen, ein Take wurde gewählt, eine neue Version ist gekommen. Nutze ihn statt zu pollen.
Webhooks werden von einem Producer oder Owner über die API verwaltet. Im Studio gibt es dafür keinen Bildschirm, und dein Claude kommt nicht heran (sie schicken Daten aus Filmsquare hinaus).
Abonnieren #
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_…"}
eventsist eine Liste von Event-Typen oder["*"]für alle.urlmuss einehttp- oderhttps-Adresse auf einem öffentlichen Host sein, ohne Benutzername oder Passwort darin.- Ein Workspace kann höchstens 10 aktive Abonnements haben. Das 11. oder das Einschalten eines weiteren über 10 hinaus antwortet mit
409und dem Codewebhook_limit.
| Route | Tut |
|---|---|
GET /workspaces/{ws}/webhooks | Abonnements listen (ohne Secrets) |
POST /workspaces/{ws}/webhooks | Abonnieren; gibt das Secret einmal zurück |
PATCH /workspaces/{ws}/webhooks/{id} | url, events oder active ändern |
DELETE /workspaces/{ws}/webhooks/{id} | Zustellungen stoppen (das Abonnement wird deaktiviert, nicht gelöscht) |
Alle vier brauchen die Rolle Producer oder höher.
Events #
| Typ | Gesendet, wenn |
|---|---|
generation.succeeded | Ein Take fertig gerendert ist |
generation.failed | Ein Render fehlgeschlagen ist (auch, wenn Filmsquare ihn von selbst wiederholt) |
take.selected | Ein Take auf einer Einstellung oder einer Szene gewählt wurde |
asset_version.created | Ein Render eine neue Asset-Version erzeugt hat |
Events zu Takes im privaten Skizzenbuch einer Person (Create) werden nie gesendet.
Die Zustellung #
Jede Zustellung ist ein POST an deine URL mit dem Event als 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 | Wert |
|---|---|
x-fs-signature | sha256= + der Hex-HMAC-SHA256 des rohen Bodys, mit deinem Secret als Schlüssel |
x-fs-event | Der Event-Typ |
x-fs-delivery | Die Event-ID. Dasselbe Event hat immer dieselbe ID |
Die Daten jedes Events #
| Typ | data-Felder |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId (der automatische nächste Versuch, oder null) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, takeId, generationId, mime |
Hol die Datei einer Asset-Version mit GET /workspaces/{ws}/asset-versions/{id}/url (eine signierte Download-URL).
Die Signatur prüfen #
Berechne den HMAC über den rohen Request-Body, genau wie empfangen, bevor du ihn parst. Der Schlüssel ist das ganze
Secret, whsec_ eingeschlossen. Vergleiche in konstanter Zeit.
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));
}
Weise eine Zustellung ab, deren Signatur nicht passt.
Antwort und Wiederholungen #
Antworte schnell mit einem beliebigen 2xx-Status. Erledige langsame Arbeit, nachdem du geantwortet hast. Filmsquare wartet höchstens 10 Sekunden auf deine Antwort; eine langsamere Antwort zählt als fehlgeschlagener Versuch.
| Deine Antwort | Was Filmsquare tut |
|---|---|
2xx | Erledigt |
5xx, 429, ein Timeout oder ein Netzwerkfehler | Versucht es nach etwa 10 Sekunden, 1 Minute und 5 Minuten erneut, bis zu 4 Versuche |
410 | Schaltet das Abonnement sofort aus |
Jedes andere 4xx | Gibt diese Zustellung auf |
Eine Zustellung kann mehr als einmal ankommen, und Events können in falscher Reihenfolge ankommen. Nutze
x-fs-delivery, um Events zu überspringen, die du schon bearbeitet hast, und createdAt, um sie zu ordnen.
Warten mehr als 500 Zustellungen auf einen Workspace, werden neue Events dafür nicht in die Warteschlange gestellt.
Wenn ein Abonnement ausgeschaltet wird #
Jeder Versuch, der kein 2xx bekommt, zählt als Fehlschlag: ein Timeout, ein Netzwerkfehler oder jeder andere Status. Ein 2xx setzt den Zähler auf 0 zurück. Filmsquare schaltet das Abonnement aus (active wird false), wenn:
- 5 oder mehr Versuche in Folge fehlgeschlagen sind und der erste davon mindestens 10 Minuten her ist, oder
- deine URL mit
410geantwortet hat, oder - deine URL öfter langsam ist als nicht. Jede Antwort, die länger als 5 Sekunden dauert, auch eine
2xx, zählt 1 zu einem Langsam-Zähler hinzu, und jede schnellere Antwort zieht 1 ab (nie unter 0). Bei 20 wird das Abonnement ausgeschaltet. Ein Timeout oder ein Netzwerkfehler zählt nur als fehlgeschlagener Versuch, nie als langsam.
Ein kurzer Ausfall, etwa durch ein Deployment, schaltet es nicht aus. Zustellungen, die für ein ausgeschaltetes Abonnement noch warten, werden nicht gesendet, und die Owner des Workspace bekommen eine Benachrichtigung in ihrer Inbox, höchstens einmal am Tag pro Abonnement. Das Abonnement zeigt, warum:
| Feld | Wert |
|---|---|
consecutive_failures | Fehlgeschlagene Versuche in Folge |
consecutive_slow | Der Langsam-Zähler: 1 mehr für jede Antwort über 5 Sekunden, 1 weniger für jede schnellere |
failing_since | Wann die aktuelle Fehlerserie begann, oder null |
disabled_at | Wann es ausgeschaltet wurde, oder null |
disabled_reason | Warum es ausgeschaltet wurde, oder null |
Um es wieder einzuschalten, aktualisiere den Webhook mit "active": true. Das setzt consecutive_failures und consecutive_slow auf 0 zurück und löscht den Grund. Ein Abonnement, das sich selbst ausgeschaltet hat, kannst du in 24 Stunden 3-mal wieder einschalten. Danach antwortet die Aktualisierung mit 409 und dem Code webhook_rearm_limit: repariere zuerst deinen Endpoint.