Filmsquare HilfeDocs

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.

Aktualisiert 4 Min. Lesezeit.md

Auf dieser Seite
  1. Abonnieren
  2. Events
  3. Die Zustellung
  4. Die Daten jedes Events
  5. Die Signatur prüfen
  6. Antwort und Wiederholungen
  7. Wenn ein Abonnement ausgeschaltet wird
  8. Verwandt

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_…"}
  • events ist eine Liste von Event-Typen oder ["*"] für alle.
  • url muss eine http- oder https-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 409 und dem Code webhook_limit.
RouteTut
GET /workspaces/{ws}/webhooksAbonnements listen (ohne Secrets)
POST /workspaces/{ws}/webhooksAbonnieren; 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 #

TypGesendet, wenn
generation.succeededEin Take fertig gerendert ist
generation.failedEin Render fehlgeschlagen ist (auch, wenn Filmsquare ihn von selbst wiederholt)
take.selectedEin Take auf einer Einstellung oder einer Szene gewählt wurde
asset_version.createdEin 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": ["…"]}}
HeaderWert
x-fs-signaturesha256= + der Hex-HMAC-SHA256 des rohen Bodys, mit deinem Secret als Schlüssel
x-fs-eventDer Event-Typ
x-fs-deliveryDie Event-ID. Dasselbe Event hat immer dieselbe ID

Die Daten jedes Events #

Typdata-Felder
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (der automatische nächste Versuch, oder null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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 AntwortWas Filmsquare tut
2xxErledigt
5xx, 429, ein Timeout oder ein NetzwerkfehlerVersucht es nach etwa 10 Sekunden, 1 Minute und 5 Minuten erneut, bis zu 4 Versuche
410Schaltet das Abonnement sofort aus
Jedes andere 4xxGibt 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 410 geantwortet 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:

FeldWert
consecutive_failuresFehlgeschlagene Versuche in Folge
consecutive_slowDer Langsam-Zähler: 1 mehr für jede Antwort über 5 Sekunden, 1 weniger für jede schnellere
failing_sinceWann die aktuelle Fehlerserie begann, oder null
disabled_atWann es ausgeschaltet wurde, oder null
disabled_reasonWarum 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.

Diese Seite als Markdown: /docs/de/api/webhooks.md