Filmsquare AjudaDocumentação

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.

Atualizado em 4 min de leitura.md

Nesta página
  1. Assinar
  2. Eventos
  3. A entrega
  4. Os dados de cada evento
  5. Conferir a assinatura
  6. Responder e novas tentativas
  7. Quando uma assinatura é desligada
  8. Relacionados

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.
  • 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.
RotaFaz
GET /workspaces/{ws}/webhooksLista as assinaturas (sem secrets)
POST /workspaces/{ws}/webhooksAssina; 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 #

TipoEnviado quando
generation.succeededUm take terminou de renderizar
generation.failedUma renderização falhou (também quando o Filmsquare tenta de novo sozinho)
take.selectedUm take foi escolhido em um plano ou cena
asset_version.createdUma 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çalhoValor
x-fs-signaturesha256= + o HMAC-SHA256 em hex do corpo bruto, com a chave do seu secret
x-fs-eventO tipo do evento
x-fs-deliveryO id do evento. O mesmo evento sempre tem o mesmo id

Os dados 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 (a próxima tentativa automática, ou null)
take.selectedselectionId, takeId, assetVersionId, shotId, sceneId, kind, selectedBy
asset_version.createdassetVersionId, 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 respostaO que o Filmsquare faz
2xxConcluído
5xx, 429, um timeout ou um erro de redeTenta de novo após cerca de 10 segundos, 1 minuto e 5 minutos, até 4 tentativas
410Desliga a assinatura na hora
Qualquer outro 4xxDesiste 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:

CampoValor
consecutive_failuresTentativas falhas seguidas
consecutive_slowA contagem de lentidão: soma 1 a cada resposta acima de 5 segundos, tira 1 a cada resposta mais rápida
failing_sinceQuando a sequência atual de falhas começou, ou null
disabled_atQuando foi desligada, ou null
disabled_reasonPor 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.

Esta página em Markdown: /docs/pt-br/api/webhooks.md