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

# Webhook

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

```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]
> Il `secret` viene restituito solo qui. Conservalo: ti serve per controllare ogni consegna.

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

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

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

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

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.

## Correlati

- [Panoramica dell'API e chiavi](https://www.filmsquare.ai/docs/it/api/overview/)
- [Riferimento OpenAPI](https://www.filmsquare.ai/docs/it/api/openapi/)
