Filmsquare HelpDocs

6.0 API6.2 Webhooks

Webhooks

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.

Bijgewerkt 4 min lezen.md

Op deze pagina
  1. Abonneren
  2. Events
  3. De bezorging
  4. De data van elk event
  5. De handtekening controleren
  6. Antwoorden en nieuwe pogingen
  7. Wanneer een abonnement wordt uitgezet
  8. Gerelateerd

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 #

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 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.
RouteDoet
GET /workspaces/{ws}/webhooksAbonnementen tonen (zonder secrets)
POST /workspaces/{ws}/webhooksAbonneren; 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 #

TypeVerstuurd als
generation.succeededEen take klaar is met renderen
generation.failedEen render mislukte (ook als Filmsquare het zelf opnieuw probeert)
take.selectedEen take is gekozen op een shot of scène
asset_version.createdEen 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:

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": ["…"]}}
HeaderWaarde
x-fs-signaturesha256= + de hex-HMAC-SHA256 van de ruwe body, met je secret als sleutel
x-fs-eventHet eventtype
x-fs-deliveryDe event-id. Hetzelfde event heeft altijd dezelfde id

De data van elk event #

Typedata-velden
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (de automatische volgende poging, of null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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.

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 antwoordWat Filmsquare doet
2xxKlaar
5xx, 429, een timeout of een netwerkfoutProbeert het opnieuw na ongeveer 10 seconden, 1 minuut en 5 minuten, tot 4 pogingen
410Zet het abonnement meteen uit
Elke andere 4xxGeeft 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:

VeldWaarde
consecutive_failuresMislukte pogingen achter elkaar
consecutive_slowDe tragheidsteller: 1 erbij voor elk antwoord trager dan 5 seconden, 1 eraf voor elk sneller antwoord
failing_sinceWanneer de huidige reeks mislukkingen begon, of null
disabled_atWanneer het is uitgezet, of null
disabled_reasonWaarom 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.

Deze pagina als Markdown: /docs/nl/api/webhooks.md