6.0 API6.2 Webhooks
Webhooks
Suscribe una URL a los eventos de Filmsquare, los cuatro tipos de evento y sus payloads, cómo se firman las entregas con x-fs-signature y cómo funcionan los reintentos.
Un webhook envía un evento a tu URL cuando pasa algo en un espacio de trabajo: una toma terminó o falló, se eligió una toma, llegó una versión nueva. Úsalo en lugar de consultar una y otra vez.
Los webhooks los gestiona un productor o un propietario mediante la API. No hay ninguna pantalla para ellos en el estudio, y tu Claude no puede llegar a ellos (envían datos fuera de Filmsquare).
Suscribirse #
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_…"}
eventses una lista de tipos de evento, o["*"]para todos.urldebe ser una direcciónhttpohttpsen un host público, sin nombre de usuario ni contraseña.- Un espacio de trabajo puede tener como máximo 10 suscripciones activas. La 11.ª, o activar una más allá de 10, responde
409con el códigowebhook_limit.
| Ruta | Hace |
|---|---|
GET /workspaces/{ws}/webhooks | Lista las suscripciones (sin secretos) |
POST /workspaces/{ws}/webhooks | Suscribe; devuelve el secreto una sola vez |
PATCH /workspaces/{ws}/webhooks/{id} | Cambia url, events o active |
DELETE /workspaces/{ws}/webhooks/{id} | Detiene las entregas (la suscripción se desactiva, no se borra) |
Las cuatro requieren el rol de productor o superior.
Eventos #
| Tipo | Se envía cuando |
|---|---|
generation.succeeded | Una toma terminó de renderizarse |
generation.failed | Un render falló (también cuando Filmsquare lo reintenta por su cuenta) |
take.selected | Se eligió una toma en un plano o una escena |
asset_version.created | Un render produjo una versión de asset nueva |
Los eventos sobre tomas del cuaderno de bocetos privado de una persona (Create) no se envían nunca.
La entrega #
Cada entrega es un POST a tu URL con el evento como cuerpo 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": ["…"]}}
| Cabecera | Valor |
|---|---|
x-fs-signature | sha256= + el HMAC-SHA256 en hexadecimal del cuerpo sin procesar, con tu secreto como clave |
x-fs-event | El tipo de evento |
x-fs-delivery | El id del evento. El mismo evento siempre tiene el mismo id |
Los datos de cada evento #
| Tipo | Campos de data |
|---|---|
generation.succeeded | generationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds |
generation.failed | generationId, takeId, tier, attempt, error, retryGenerationId (el siguiente intento automático, o null) |
take.selected | selectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy |
asset_version.created | assetVersionId, takeId, generationId, mime |
Obtén el archivo de una versión de asset con GET /workspaces/{ws}/asset-versions/{id}/url (una URL de descarga
firmada).
Comprueba la firma #
Calcula el HMAC sobre el cuerpo sin procesar de la petición, exactamente como se recibió, antes de analizarlo. La
clave es el secreto entero, whsec_ incluido. Compara en tiempo constante.
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));
}
Rechaza una entrega cuya firma no coincida.
Respuesta y reintentos #
Responde con cualquier estado 2xx, rápido. Haz el trabajo lento después de responder. Filmsquare espera como máximo 10 segundos tu respuesta; una respuesta más lenta cuenta como un intento fallido.
| Tu respuesta | Qué hace Filmsquare |
|---|---|
2xx | Hecho |
5xx, 429, un timeout o un error de red | Reintenta tras unos 10 segundos, 1 minuto y 5 minutos, hasta 4 intentos |
410 | Apaga la suscripción de inmediato |
Cualquier otro 4xx | Abandona esta entrega |
Una entrega puede llegar más de una vez, y los eventos pueden llegar desordenados. Usa x-fs-delivery para saltarte
los eventos que ya gestionaste, y createdAt para ordenarlos.
Si hay más de 500 entregas esperando para un espacio de trabajo, los eventos nuevos de ese espacio no se ponen en cola.
Cuando una suscripción se apaga #
Todo intento que no recibe un 2xx cuenta como fallido: un timeout, un error de red o cualquier otro estado. Un 2xx vuelve a poner la cuenta en 0. Filmsquare apaga la suscripción (active pasa a false) cuando:
- fallaron 5 o más intentos seguidos y el primero fue hace al menos 10 minutos, o
- tu URL respondió
410, o - tu URL es lenta más veces que no. Cada respuesta que tarda más de 5 segundos, incluso un
2xx, suma 1 a una cuenta de lentitud, y cada respuesta más rápida resta 1 (nunca por debajo de 0). Al llegar a 20, la suscripción se apaga. Un timeout o un error de red cuenta solo como intento fallido, nunca como lento.
Una caída corta, como un despliegue, no la apaga. Las entregas que aún esperan a una suscripción apagada no se envían, y los propietarios del espacio de trabajo reciben una notificación en su bandeja de entrada, como mucho una vez al día por suscripción. La suscripción muestra por qué:
| Campo | Valor |
|---|---|
consecutive_failures | Intentos fallidos seguidos |
consecutive_slow | La cuenta de lentitud: suma 1 por cada respuesta de más de 5 segundos, resta 1 por cada una más rápida |
failing_since | Cuándo empezó la racha de fallos actual, o null |
disabled_at | Cuándo se apagó, o null |
disabled_reason | Por qué se apagó, o null |
Para volver a activarla, actualiza el webhook con "active": true. Eso vuelve a poner consecutive_failures y consecutive_slow en 0 y borra el motivo. Una suscripción que se apagó sola se puede volver a activar 3 veces en 24 horas. Después, la actualización responde 409 con el código webhook_rearm_limit: arregla primero tu endpoint.