6.0 API6.2 Webhooks
Webhooks
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.
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 #
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é uma lista de tipos de evento, ou["*"]para todos.urlprecisa ser um endereçohttpouhttpsem 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
409com o códigowebhook_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:
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.
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.