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

# Webhooks

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

```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]
> El `secret` se devuelve solo aquí. Guárdalo: lo necesitas para comprobar cada entrega.

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

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

```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": ["…"]}}
```

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

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

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.

## Relacionado

- [Resumen de la API y claves](https://www.filmsquare.ai/docs/es/api/overview/)
- [Referencia OpenAPI](https://www.filmsquare.ai/docs/es/api/openapi/)
