Receba notificações de projetos

Crie um destino

Após a abertura, adicione um receptor HTTPS público em Configurações → Integrações, escolha eventos e guarde o segredo de assinatura exibido uma única vez. Também é possível usar uma chave com webhooks:manage:

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"]}'

Substitua pela URL real. Somente HTTPS público na porta 443 é aceito, sem redirecionamentos. Localhost e redes privadas não recebem entregas diretamente.

Escolha eventos

project.completed: exportação concluída; padrão.
project.failed: processamento ou exportação falhou; padrão.
project.ready: processamento completo, pronto para revisar ou exportar.
project.cancelled: projeto cancelado.

Inclui vídeos elegíveis da sua conta criados no aplicativo, REST ou MCP. Exclui Transcripts independentes, projetos excluídos ou fora do prazo de acesso. Ready não confirma revisão humana.

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

data.resultUrl é um endpoint autenticado, não o vídeo. Consulte-o com sua API Key de leitura para obter links novos. Eventos contêm metadados, não vídeos ou legendas.

Verifique antes de processar

O formato segue Standard Webhooks. Use um verificador compatível ou aplique estas verificações:

Preserve o corpo original e leia webhook-id, webhook-timestamp e webhook-signature.
Remova whsec_, decodifique o segredo em base64 e calcule HMAC-SHA256 sobre id.timestamp.rawBody. Compare a assinatura base64 em tempo constante.
Rejeite horários passados ou futuros fora de uma tolerância limitada, como cinco minutos. Na rotação, podem existir várias assinaturas v1, separadas por espaços; aceite uma que corresponda a uma chave confiável.
Elimine duplicados por ID de evento e persista o trabalho antes de responder 2xx. Processe a tarefa de forma assíncrona e confirme antes do prazo de 15 segundos.

O segredo de assinatura é separado da API Key. A rotação exibe o novo segredo uma vez e permite 24 horas de sobreposição; outra rotação fica bloqueada nesse período.

Teste e recupere entregas

O teste nas configurações envia webhook.test; trate-o separadamente. Consulte o histórico dos últimos 30 dias, corrija o receptor e repita manualmente uma entrega falha ou já entregue.

Eventos podem se repetir e chegar fora de ordem. Respostas não 2xx, falhas de conexão ou falta de confirmação permitem três tentativas automáticas no total: a inicial e outras após cerca de um e cinco minutos. A terceira falha encerra a entrega automática. A tentativa manual mantém o ID e restaura as três tentativas; o receptor deve ser idempotente.

Desativar interrompe entregas pendentes, mas uma requisição em andamento pode terminar. Excluir o destino apaga seu histórico. Exclusão ou expiração do projeto interrompe notificações pendentes. Webhooks não ampliam o acesso à mídia: salve os resultados a tempo ou consulte o estado do projeto.