Filmsquare AiutoDocumentazione

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.

Aggiornato il 4 min di lettura.md

In questa pagina
  1. Iscriversi
  2. Eventi
  3. La consegna
  4. I dati di ogni evento
  5. Controllare la firma
  6. Rispondere e nuovi tentativi
  7. Quando un'iscrizione viene disattivata
  8. Correlati

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.
  • url deve essere un indirizzo http o https su 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 409 con il codice webhook_limit.
RottaCosa fa
GET /workspaces/{ws}/webhooksElenca le iscrizioni (senza segreti)
POST /workspaces/{ws}/webhooksIscrive; 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 #

TipoInviato quando
generation.succeededUn ciak ha finito il render
generation.failedUn render è fallito (anche quando Filmsquare lo riprova da solo)
take.selectedUn ciak è stato scelto su un'inquadratura o una scena
asset_version.createdUn 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": ["…"]}}
HeaderValore
x-fs-signaturesha256= + l'HMAC-SHA256 esadecimale del corpo grezzo, con il tuo segreto come chiave
x-fs-eventIl tipo di evento
x-fs-deliveryL'id dell'evento. Lo stesso evento ha sempre lo stesso id

I dati di ogni evento #

TipoCampi di data
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (il tentativo automatico successivo, o null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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 rispostaCosa fa Filmsquare
2xxFatto
5xx, 429, un timeout o un errore di reteRiprova dopo circa 10 secondi, 1 minuto e 5 minuti, fino a 4 tentativi
410Disattiva subito l'iscrizione
Qualsiasi altro 4xxRinuncia 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é:

CampoValore
consecutive_failuresTentativi falliti di fila
consecutive_slowIl conteggio di lentezza: +1 per ogni risposta oltre i 5 secondi, −1 per ogni risposta più rapida
failing_sinceQuando è iniziata la serie di fallimenti in corso, oppure null
disabled_atQuando è stata disattivata, oppure null
disabled_reasonPerché è 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.

Questa pagina in Markdown: /docs/it/api/webhooks.md