---
title: "Webhooks"
description: "Abonneer een URL op Filmsquare-events, de vier eventtypes en hun payloads, hoe bezorgingen worden ondertekend met x-fs-signature en hoe nieuwe pogingen werken."
url: https://www.filmsquare.ai/docs/nl/api/webhooks/
lang: nl
section: api
updated: 2026-11-17
---

# Webhooks

Een webhook stuurt een event naar je URL als er iets gebeurt in een workspace: een take is klaar of mislukt, een take is
gekozen, er is een nieuwe versie binnengekomen. Gebruik hem in plaats van te pollen.

Webhooks worden via de API beheerd door een producent of eigenaar. Er is geen scherm voor in de studio, en je
Claude kan ze niet bereiken (ze sturen data uit Filmsquare).

## Abonneren

```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]
> De `secret` wordt alleen hier teruggegeven. Bewaar hem: je hebt hem nodig om elke bezorging te controleren.

- `events` is een lijst met eventtypes, of `["*"]` voor allemaal.
- `url` moet een `http`- of `https`-adres op een openbare host zijn, zonder gebruikersnaam of wachtwoord erin.
- Een workspace kan maximaal 10 actieve abonnementen hebben. Het 11e, of er een aanzetten boven de 10, antwoordt met `409` en de code `webhook_limit`.

| Route | Doet |
| --- | --- |
| `GET /workspaces/{ws}/webhooks` | Abonnementen tonen (zonder secrets) |
| `POST /workspaces/{ws}/webhooks` | Abonneren; geeft de secret één keer terug |
| `PATCH /workspaces/{ws}/webhooks/{id}` | `url`, `events` of `active` wijzigen |
| `DELETE /workspaces/{ws}/webhooks/{id}` | Bezorging stoppen (het abonnement wordt gedeactiveerd, niet verwijderd) |

Alle vier vragen de rol producent of hoger.

## Events

| Type | Verstuurd als |
| --- | --- |
| `generation.succeeded` | Een take klaar is met renderen |
| `generation.failed` | Een render mislukte (ook als Filmsquare het zelf opnieuw probeert) |
| `take.selected` | Een take is gekozen op een shot of scène |
| `asset_version.created` | Een render een nieuwe assetversie opleverde |

Events over takes in het privéschetsboek van iemand (Create) worden nooit verstuurd.

## De bezorging

Elke bezorging is een `POST` naar je URL met het 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 | Waarde |
| --- | --- |
| `x-fs-signature` | `sha256=` + de hex-HMAC-SHA256 van de ruwe body, met je secret als sleutel |
| `x-fs-event` | Het eventtype |
| `x-fs-delivery` | De event-id. Hetzelfde event heeft altijd dezelfde id |

### De data van elk event

| Type | `data`-velden |
| --- | --- |
| `generation.succeeded` | `generationId`, `takeId`, `shotId`, `sceneId`, `elementId`, `kind`, `tier`, `provider`, `modelKey`, `costCredits`, `assetVersionIds` |
| `generation.failed` | `generationId`, `takeId`, `tier`, `attempt`, `error`, `retryGenerationId` (de automatische volgende poging, of `null`) |
| `take.selected` | `selectionId`, `takeId`, `assetVersionId`, `shotId`, `sceneId`, `kind`, `selectedBy` |
| `asset_version.created` | `assetVersionId`, `takeId`, `generationId`, `mime` |

Haal het bestand van een assetversie op met `GET /workspaces/{ws}/asset-versions/{id}/url` (een ondertekende download-URL).

## De handtekening controleren

Bereken de HMAC over de ruwe request-body, precies zoals ontvangen, voordat je hem parset. De sleutel is de hele secret,
`whsec_` inbegrepen. Vergelijk in constante tijd.

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

Weiger een bezorging waarvan de handtekening niet klopt.

## Antwoorden en nieuwe pogingen

Antwoord snel met een willekeurige `2xx`-status. Doe trage klussen nadat je hebt geantwoord. Filmsquare wacht maximaal 10 seconden op je antwoord; een trager antwoord telt als een mislukte poging.

| Jouw antwoord | Wat Filmsquare doet |
| --- | --- |
| `2xx` | Klaar |
| `5xx`, `429`, een timeout of een netwerkfout | Probeert het opnieuw na ongeveer 10 seconden, 1 minuut en 5 minuten, tot 4 pogingen |
| `410` | Zet het abonnement meteen uit |
| Elke andere `4xx` | Geeft deze bezorging op |

Een bezorging kan meer dan eens aankomen, en events kunnen in de verkeerde volgorde aankomen. Gebruik `x-fs-delivery` om events over te slaan die je al
hebt afgehandeld, en `createdAt` om ze te ordenen.

Wachten er meer dan 500 bezorgingen voor één workspace, dan komen nieuwe events daarvoor niet in de wachtrij.

### Wanneer een abonnement wordt uitgezet

Elke poging die geen `2xx` krijgt, telt als mislukt: een timeout, een netwerkfout of elke andere status. Een `2xx` zet de teller terug op 0. Filmsquare zet het abonnement uit (`active` wordt `false`) wanneer:

- 5 of meer pogingen achter elkaar mislukten en de eerste daarvan minstens 10 minuten geleden was, of
- je URL met `410` antwoordde, of
- je URL vaker traag is dan niet. Elk antwoord dat langer dan 5 seconden duurt, ook een `2xx`, telt 1 op bij een tragheidsteller, en elk sneller antwoord haalt er 1 af (nooit onder 0). Bij 20 wordt het abonnement uitgezet. Een timeout of een netwerkfout telt alleen als mislukte poging, nooit als traag.

Een korte storing, zoals een deploy, zet het niet uit. Bezorgingen die nog wachten op een uitgezet abonnement worden niet verstuurd, en de eigenaren van de workspace krijgen een melding in hun inbox, hooguit één keer per dag per abonnement. Het abonnement laat zien waarom:

| Veld | Waarde |
| --- | --- |
| `consecutive_failures` | Mislukte pogingen achter elkaar |
| `consecutive_slow` | De tragheidsteller: 1 erbij voor elk antwoord trager dan 5 seconden, 1 eraf voor elk sneller antwoord |
| `failing_since` | Wanneer de huidige reeks mislukkingen begon, of `null` |
| `disabled_at` | Wanneer het is uitgezet, of `null` |
| `disabled_reason` | Waarom het is uitgezet, of `null` |

Om het weer aan te zetten werk je de webhook bij met `"active": true`. Dat zet `consecutive_failures` en `consecutive_slow` terug op 0 en wist de reden. Een abonnement dat zichzelf uitzette, kun je in 24 uur 3 keer weer aanzetten. Daarna antwoordt de update met `409` en de code `webhook_rearm_limit`: herstel eerst je endpoint.

## Gerelateerd

- [API-overzicht en sleutels](https://www.filmsquare.ai/docs/nl/api/overview/)
- [OpenAPI-referentie](https://www.filmsquare.ai/docs/nl/api/openapi/)
