6.0 API6.2 Webhook
Webhook
Iscrivi un URL agli eventi di Filmsquare, i quattro tipi di evento e i loro payload, come vengono firmate le consegne con x-fs-signature e come funzionano i nuovi tentativi.
Un webhook manda un evento al tuo URL quando succede qualcosa in uno spazio di lavoro: un ciak è finito o fallito, un ciak è stato scelto, è arrivata una nuova versione. Usalo al posto di interrogare di continuo.
I webhook si gestiscono tramite l'API, da un produttore o proprietario. Nello studio non c'è nessuna schermata per loro, e il tuo Claude non può raggiungerli (mandano dati fuori da Filmsquare).
Iscriversi #
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è un elenco di tipi di evento, oppure["*"]per tutti.urldeve essere un indirizzohttpohttpssu un host pubblico, senza nome utente o password al suo interno.- Uno spazio di lavoro può avere al massimo 10 iscrizioni attive. L'11ª, o attivarne una oltre le 10, risponde
409con il codicewebhook_limit.
| Rotta | Cosa fa |
|---|---|
GET /workspaces/{ws}/webhooks | Elenca le iscrizioni (senza segreti) |
POST /workspaces/{ws}/webhooks | Iscrive; restituisce il segreto una volta sola |
PATCH /workspaces/{ws}/webhooks/{id} | Cambia url, events o active |
DELETE /workspaces/{ws}/webhooks/{id} | Ferma le consegne (l'iscrizione viene disattivata, non cancellata) |
Tutte e quattro richiedono il ruolo di produttore o superiore.
Eventi #
| Tipo | Inviato quando |
|---|---|
generation.succeeded | Un ciak ha finito il render |
generation.failed | Un render è fallito (anche quando Filmsquare lo riprova da solo) |
take.selected | Un ciak è stato scelto su un'inquadratura o una scena |
asset_version.created | Un render ha prodotto una nuova versione di asset |
Gli eventi sui ciak nel quaderno di schizzi privato di una persona (Create) non vengono mai inviati.
La consegna #
Ogni consegna è un POST al tuo URL con l'evento come corpo JSON:
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 | Valore |
|---|---|
x-fs-signature | sha256= + l'HMAC-SHA256 esadecimale del corpo grezzo, con il tuo segreto come chiave |
x-fs-event | Il tipo di evento |
x-fs-delivery | L'id dell'evento. Lo stesso evento ha sempre lo stesso id |
I dati di ogni evento #
| Tipo | Campi di data |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId (il tentativo automatico successivo, o null) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, takeId, generationId, mime |
Recupera il file di una versione di asset con GET /workspaces/{ws}/asset-versions/{id}/url (un URL di download
firmato).
Controllare la firma #
Calcola l'HMAC sul corpo grezzo della richiesta, esattamente come ricevuto, prima di farne il parsing. La chiave è
l'intero segreto, whsec_ compreso. Confronta in tempo costante.
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));
}
Rifiuta una consegna la cui firma non corrisponde.
Rispondere e nuovi tentativi #
Rispondi con qualsiasi stato 2xx, in fretta. Fai il lavoro lento dopo aver risposto. Filmsquare aspetta la tua risposta al massimo 10 secondi; una risposta più lenta conta come un tentativo fallito.
| La tua risposta | Cosa fa Filmsquare |
|---|---|
2xx | Fatto |
5xx, 429, un timeout o un errore di rete | Riprova dopo circa 10 secondi, 1 minuto e 5 minuti, fino a 4 tentativi |
410 | Disattiva subito l'iscrizione |
Qualsiasi altro 4xx | Rinuncia a questa consegna |
Una consegna può arrivare più di una volta, e gli eventi possono arrivare fuori ordine. Usa x-fs-delivery per
saltare gli eventi che hai già gestito, e createdAt per ordinarli.
Se più di 500 consegne sono in attesa per uno spazio di lavoro, i nuovi eventi di quello spazio non vengono messi in coda.
Quando un'iscrizione viene disattivata #
Ogni tentativo che non riceve un 2xx conta come fallito: un timeout, un errore di rete o qualsiasi altro stato. Un 2xx riporta il conteggio a 0. Filmsquare disattiva l'iscrizione (active diventa false) quando:
- 5 o più tentativi di fila sono falliti e il primo risale ad almeno 10 minuti fa, oppure
- il tuo URL ha risposto
410, oppure - il tuo URL è lento più spesso che no. Ogni risposta che impiega più di 5 secondi, anche un
2xx, aggiunge 1 a un conteggio di lentezza, e ogni risposta più rapida ne toglie 1 (mai sotto 0). A 20 l'iscrizione viene disattivata. Un timeout o un errore di rete conta solo come tentativo fallito, mai come lento.
Un breve disservizio, come un deploy, non la disattiva. Le consegne ancora in attesa per un'iscrizione disattivata non vengono inviate, e i proprietari dello spazio di lavoro ricevono una notifica nella loro Inbox, al massimo una volta al giorno per iscrizione. L'iscrizione mostra il perché:
| Campo | Valore |
|---|---|
consecutive_failures | Tentativi falliti di fila |
consecutive_slow | Il conteggio di lentezza: +1 per ogni risposta oltre i 5 secondi, −1 per ogni risposta più rapida |
failing_since | Quando è iniziata la serie di fallimenti in corso, oppure null |
disabled_at | Quando è stata disattivata, oppure null |
disabled_reason | Perché è stata disattivata, oppure null |
Per riattivarla, aggiorna il webhook con "active": true. Così consecutive_failures e consecutive_slow tornano a 0 e il motivo viene cancellato. Un'iscrizione che si è disattivata da sola può essere riattivata 3 volte in 24 ore. Dopo, l'aggiornamento risponde 409 con il codice webhook_rearm_limit: sistema prima il tuo endpoint.