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

# Webhooks

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

```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]
> Das `secret` wird nur hier zurückgegeben. Bewahre es auf: Du brauchst es, um jede Zustellung zu prüfen.

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

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

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

```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));
}
```

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

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

## Verwandt

- [API-Überblick und Schlüssel](https://www.filmsquare.ai/docs/de/api/overview/)
- [OpenAPI-Referenz](https://www.filmsquare.ai/docs/de/api/openapi/)
