Receba notificações de projetos

Prepare seu receptor

Webhooks enviam HTTP quando um vídeo está pronto para revisão, a exportação termina, falha ou o projeto é cancelado. As integrações estão disponíveis nas assinaturas Max.

É necessária uma URL HTTPS pública que aceite POST, apenas na porta 443. Localhost e redes privadas não recebem diretamente. Não há redirecionamentos; para teste local, use túnel HTTPS público.

Troque https://receiver.example/captionbolt pela URL real.

Adicione um endpoint

Abra Configurações → Integrações.
Informe URL HTTPS de destino e escolha eventos.
Selecione Adicionar Webhook.
Guarde o segredo de assinatura; é exibido uma única vez.

Esse segredo verifica notificações e é diferente de uma chave API.

Também pode criar por REST. Configure CAPTIONBOLT_API_KEY com webhooks:manage conforme o guia API:

curl --fail-with-body https://api.captionbolt.com/v1/webhooks \
  -H "Authorization: Bearer $CAPTIONBOLT_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"url":"https://receiver.example/captionbolt","events":["project.completed","project.failed"]}'

A resposta traz id e secret. Guarde o segredo com segurança no ambiente do receptor.

Escolha eventos

| Evento | Significado | | --- | --- | | project.ready | Processamento completo; pode revisar ou exportar | | project.completed | Exportação concluída e resultados disponíveis; padrão | | project.failed | Processamento ou exportação falhou; padrão | | project.cancelled | Projeto cancelado |

Eventos cobrem projetos de vídeo elegíveis criados pelo site, REST ou MCP. Novo endpoint recebe eventos futuros, sem repetir mudanças anteriores. Excluem Transcripts independentes e projetos excluídos ou fora do acesso.

project.ready não significa exportado nem revisado por uma pessoa.

{
  "id": "event-uuid",
  "type": "project.completed",
  "createdAt": "2026-09-27T12:00:00.000Z",
  "data": {
    "projectId": "project-uuid",
    "status": "completed",
    "stage": "export",
    "resultUrl": "https://api.captionbolt.com/v1/projects/project-uuid/result"
  }
}

Eventos trazem metadados, não vídeo ou legendas. data.resultUrl é REST autenticado. Use chave com projects:read para obter links novos; baixe arquivos sem enviar a chave. Veja downloads.

Verifique as solicitações

CaptionBolt usa Standard Webhooks. Verifique a assinatura com o corpo bruto exato antes de interpretar ou agir. Cabeçalhos: webhook-id, webhook-timestamp, webhook-signature.

Exemplo de receptor Node.js

Este receptor verifica assinaturas e registra ID e tipo para teste. O exemplo usa Node.js 24; outro idioma de programação também serve. Instale o verificador JavaScript no seu projeto receptor:

npm install standardwebhooks
read -r -s -p 'CaptionBolt signing secret: ' CAPTIONBOLT_WEBHOOK_SECRET
export CAPTIONBOLT_WEBHOOK_SECRET
printf '\n'

Salve como receiver.mjs:

import { createServer } from "node:http";
import { Webhook } from "standardwebhooks";

const secret = process.env.CAPTIONBOLT_WEBHOOK_SECRET;
if (!secret) throw new Error("Set CAPTIONBOLT_WEBHOOK_SECRET.");
const verifier = new Webhook(secret);

createServer(async (request, response) => {
  if (request.method !== "POST" || request.url !== "/captionbolt") {
    response.writeHead(404).end();
    return;
  }
  let event;
  try {
    const chunks = [];
    let size = 0;
    for await (const chunk of request) {
      size += chunk.length;
      if (size > 65536) {
        response.writeHead(413).end();
        return;
      }
      chunks.push(chunk);
    }
    const rawBody = Buffer.concat(chunks).toString("utf8");
    event = verifier.verify(rawBody, {
      "webhook-id": request.headers["webhook-id"],
      "webhook-timestamp": request.headers["webhook-timestamp"],
      "webhook-signature": request.headers["webhook-signature"],
    });
  } catch {
    response.writeHead(400).end("Invalid webhook");
    return;
  }
  console.log("Verified event:", event.id, event.type);
  response.writeHead(204).end();
}).listen(3000, "127.0.0.1");

Execute node receiver.mjs e exponha /captionbolt por HTTPS ou túnel público. O CaptionBolt precisa da URL HTTPS pública, não do endereço local.

O verificador confere assinatura e timestamp; mantenha o relógio correto. Não interprete e serialize novamente JSON antes da verificação, nem registre segredo ou corpo completo.

Em produção, substitua logs por recebimento persistente: deduplique por id, salve evento ou tarefa antes do 2xx e processe assincronamente. Falha de persistência deve retornar erro para permitir nova tentativa. O exemplo só testa recebimento; não fornece fila persistente ou downloads.

Envie um teste

Inicie o receptor e configure o segredo.
Abra o endpoint em Configurações → Integrações e selecione Enviar teste.
Confira Histórico de entregas.
Confirme um webhook.test verificado nos logs.

Só um teste pode estar ativo por endpoint. Aguarde terminar e mais 60 segundos antes de outro. Novas tentativas manuais também têm intervalo mínimo; siga o tempo retornado.

Trate webhook.test separadamente: não representa vídeo concluído. Use evento real futuro para testar resultados.

Se falhar, confira URL, segredo, corpo bruto e resposta. Confirme em 15 segundos. Resposta não 2xx, erro de conexão ou ausência de confirmação provoca novas tentativas.

Gerencie novas tentativas e segredos

Notificações podem repetir ou chegar fora de ordem. Deduplique por ID e consulte o estado atual quando necessário.

São três tentativas automáticas: inicial, cerca de um minuto após a primeira falha e cinco minutos após a segunda. Depois, a entrega automática para. Corrija o receptor e selecione Reenviar; mantém o ID e inicia outras três tentativas. O histórico dura 30 dias.

Use Rotacionar segredo, guarde o segredo novo e atualize o receptor. O anterior vale 24 horas; ambas as assinaturas acompanham entregas nesse período. Outra rotação fica bloqueada até acabar a sobreposição.

Desativar interrompe entregas pendentes; uma requisição em andamento pode terminar. Excluir remove também o histórico. Excluir o projeto ou encerrar seu acesso interrompe notificações pendentes. Webhooks não ampliam os 14 dias; obtenha e salve resultados antes.