Filmsquare AyudaDocumentación

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.

Actualizado 4 min de lectura.md

En esta página
  1. Suscribirse
  2. Eventos
  3. La entrega
  4. Los datos de cada evento
  5. Comprueba la firma
  6. Respuesta y reintentos
  7. Cuando una suscripción se apaga
  8. Relacionado

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_…"}
  • events es una lista de tipos de evento, o ["*"] para todos.
  • url debe ser una dirección http o https en 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 409 con el código webhook_limit.
RutaHace
GET /workspaces/{ws}/webhooksLista las suscripciones (sin secretos)
POST /workspaces/{ws}/webhooksSuscribe; 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 #

TipoSe envía cuando
generation.succeededUna toma terminó de renderizarse
generation.failedUn render falló (también cuando Filmsquare lo reintenta por su cuenta)
take.selectedSe eligió una toma en un plano o una escena
asset_version.createdUn 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": ["…"]}}
CabeceraValor
x-fs-signaturesha256= + el HMAC-SHA256 en hexadecimal del cuerpo sin procesar, con tu secreto como clave
x-fs-eventEl tipo de evento
x-fs-deliveryEl id del evento. El mismo evento siempre tiene el mismo id

Los datos de cada evento #

TipoCampos de data
generation.succeededgenerationId, takeId, shotId, sceneId, elementId, kind, tier, provider, modelKey, costCredits, assetVersionIds
generation.failedgenerationId, takeId, tier, attempt, error, retryGenerationId (el siguiente intento automático, o null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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 respuestaQué hace Filmsquare
2xxHecho
5xx, 429, un timeout o un error de redReintenta tras unos 10 segundos, 1 minuto y 5 minutos, hasta 4 intentos
410Apaga la suscripción de inmediato
Cualquier otro 4xxAbandona 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é:

CampoValor
consecutive_failuresIntentos fallidos seguidos
consecutive_slowLa cuenta de lentitud: suma 1 por cada respuesta de más de 5 segundos, resta 1 por cada una más rápida
failing_sinceCuándo empezó la racha de fallos actual, o null
disabled_atCuándo se apagó, o null
disabled_reasonPor 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.

Esta página en Markdown: /docs/es/api/webhooks.md