---
title: "Webhooks"
description: "Assine uma URL para eventos do Filmsquare, os quatro tipos de evento e os seus payloads, como as entregas são assinadas com x-fs-signature e como funcionam as novas tentativas."
url: https://www.filmsquare.ai/docs/pt-br/api/webhooks/
lang: pt-BR
section: api
updated: 2026-11-17
---

# Webhooks

Um webhook envia um evento à sua URL quando algo acontece em um espaço de trabalho: um take terminou ou falhou, um take foi
escolhido, uma nova versão chegou. Use no lugar de consultar de tempos em tempos.

Os webhooks são gerenciados pela API por um(a) produtor(a) ou proprietário(a). Não há tela para eles no estúdio, e o seu
Claude não os alcança (eles mandam dados para fora do Filmsquare).

## Assinar

```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]
> O `secret` é devolvido só aqui. Guarde-o: você precisa dele para conferir cada entrega.

- `events` é uma lista de tipos de evento, ou `["*"]` para todos.
- `url` precisa ser um endereço `http` ou `https` em um host público, sem usuário nem senha.
- Um espaço de trabalho pode ter no máximo 10 assinaturas ativas. A 11ª, ou ativar mais uma além de 10, responde `409` com o código `webhook_limit`.

| Rota | Faz |
| --- | --- |
| `GET /workspaces/{ws}/webhooks` | Lista as assinaturas (sem secrets) |
| `POST /workspaces/{ws}/webhooks` | Assina; devolve o secret uma vez |
| `PATCH /workspaces/{ws}/webhooks/{id}` | Altera `url`, `events` ou `active` |
| `DELETE /workspaces/{ws}/webhooks/{id}` | Para as entregas (a assinatura é desativada, não apagada) |

As quatro exigem a função de produtor(a) ou acima.

## Eventos

| Tipo | Enviado quando |
| --- | --- |
| `generation.succeeded` | Um take terminou de renderizar |
| `generation.failed` | Uma renderização falhou (também quando o Filmsquare tenta de novo sozinho) |
| `take.selected` | Um take foi escolhido em um plano ou cena |
| `asset_version.created` | Uma renderização produziu uma nova versão de material |

Eventos sobre takes no caderno de rascunhos privado de uma pessoa (Create) nunca são enviados.

## A entrega

Cada entrega é um `POST` à sua URL com o evento como 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": ["…"]}}
```

| Cabeçalho | Valor |
| --- | --- |
| `x-fs-signature` | `sha256=` + o HMAC-SHA256 em hex do corpo bruto, com a chave do seu secret |
| `x-fs-event` | O tipo do evento |
| `x-fs-delivery` | O id do evento. O mesmo evento sempre tem o mesmo id |

### Os dados 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` (a próxima tentativa automática, ou `null`) |
| `take.selected` | `selectionId`, `takeId`, `assetVersionId`, `shotId`, `sceneId`, `kind`, `selectedBy` |
| `asset_version.created` | `assetVersionId`, `takeId`, `generationId`, `mime` |

Busque o arquivo de uma versão de material com `GET /workspaces/{ws}/asset-versions/{id}/url` (uma URL de download assinada).

## Conferir a assinatura

Calcule o HMAC sobre o corpo bruto da requisição, exatamente como recebido, antes de interpretá-lo. A chave é o secret inteiro,
`whsec_` incluído. Compare em tempo 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));
}
```

Rejeite uma entrega cuja assinatura não bate.

## Responder e novas tentativas

Responda com qualquer status `2xx`, rápido. Faça o trabalho lento depois de responder. O Filmsquare espera no máximo 10 segundos pela sua resposta; uma resposta mais lenta conta como tentativa falha.

| A sua resposta | O que o Filmsquare faz |
| --- | --- |
| `2xx` | Concluído |
| `5xx`, `429`, um timeout ou um erro de rede | Tenta de novo após cerca de 10 segundos, 1 minuto e 5 minutos, até 4 tentativas |
| `410` | Desliga a assinatura na hora |
| Qualquer outro `4xx` | Desiste desta entrega |

Uma entrega pode chegar mais de uma vez, e os eventos podem chegar fora de ordem. Use `x-fs-delivery` para pular eventos que você
já tratou, e `createdAt` para ordená-los.

Se mais de 500 entregas estiverem esperando em um espaço de trabalho, os novos eventos dele não entram na fila.

### Quando uma assinatura é desligada

Toda tentativa que não recebe um `2xx` conta como falha: um timeout, um erro de rede ou qualquer outro status. Uma resposta `2xx` zera a contagem. O Filmsquare desliga a assinatura (`active` vira `false`) quando:

- 5 ou mais tentativas seguidas falharam e a primeira delas foi há pelo menos 10 minutos, ou
- a sua URL respondeu `410`, ou
- a sua URL é lenta na maior parte das vezes. Cada resposta que demora mais de 5 segundos, mesmo um `2xx`, soma 1 a uma contagem de lentidão, e cada resposta mais rápida tira 1 (nunca abaixo de 0). Ao chegar a 20, a assinatura é desligada. Um timeout ou um erro de rede conta só como tentativa falha, nunca como lenta.

Uma queda curta, como um deploy, não a desliga. As entregas que ainda esperam por uma assinatura desligada não são enviadas, e os proprietários do espaço de trabalho recebem uma notificação na caixa de entrada, no máximo uma vez por dia por assinatura. A assinatura mostra o motivo:

| Campo | Valor |
| --- | --- |
| `consecutive_failures` | Tentativas falhas seguidas |
| `consecutive_slow` | A contagem de lentidão: soma 1 a cada resposta acima de 5 segundos, tira 1 a cada resposta mais rápida |
| `failing_since` | Quando a sequência atual de falhas começou, ou `null` |
| `disabled_at` | Quando foi desligada, ou `null` |
| `disabled_reason` | Por que foi desligada, ou `null` |

Para ligá-la de novo, atualize o webhook com `"active": true`. Isso zera `consecutive_failures` e `consecutive_slow` e apaga o motivo. Uma assinatura que se desligou sozinha pode ser ligada de novo 3 vezes em 24 horas. Depois disso, a atualização responde `409` com o código `webhook_rearm_limit`: conserte o seu endpoint primeiro.

## Relacionados

- [Visão geral da API e chaves](https://www.filmsquare.ai/docs/pt-br/api/overview/)
- [Referência OpenAPI](https://www.filmsquare.ai/docs/pt-br/api/openapi/)
