Inclua webhook_url no request
Você pode enviar webhook_url com um link de vídeo, na reserva de um upload em partes ou como campo de um upload multipart. Não combine com reuse_recent. Veja como configurar a URL.
Webhooks atendem a processos que continuam depois do request inicial, como transcrever entrevistas enviadas por upload ou montar um arquivo de episódios. Salve o ID da transcrição junto do registro da sua aplicação para ligar o evento à ação que o usuário iniciou.
Use o endpoint HTTPS público final, sem redirecionamento. O destino é validado na criação e na entrega; localhost não serve como receptor. O exemplo abaixo envia um arquivo, então você pode testar a notificação com uma gravação sua.
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
-H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
-F [email protected] \
-F webhook_url=https://example.com/hooks/transcript1Registre o evento antes de iniciar o próximo passo
data traz o objeto da transcrição, sem o texto. Use data.id e type para reconhecer entregas repetidas. Se o evento confirmar a conclusão, consulte a transcrição pela API.
Prepare seu endpoint para receber o mesmo evento mais de uma vez. Ele pode processar a chamada, mas demorar além de 10 segundos para responder e provocar uma nova tentativa. Salve uma chave com ID da transcrição e tipo do evento antes de publicar um texto ou notificar o usuário.
Depois de verificar a assinatura, grave o evento de forma persistente ou coloque-o numa fila e responda 2xx rapidamente. Busque o texto em segundo plano usando data.id. Em transcription.failed, confira data.error e atualize o status na sua aplicação. Como cancelamentos não geram callback, o seu fluxo de cancelamento precisa atualizar o próprio registro.
X-Transcript1-Signature: t=<unix seconds>,v1=<hex digest>
{
"type": "transcription.completed",
"created_at": "2026-10-13T09:30:04.000Z",
"data": {
"id": "tr_8fK2Lm0PqRsTuVwXyZaBcD",
"object": "transcription",
"status": "completed",
"transcript_source": "speech_to_text",
"billed_minutes": 4,
"error": null
}
}Como verificar a assinatura HMAC do webhook
Calcule o HMAC-SHA256 de t + ponto + corpo original usando o segredo whsec_. Compare em tempo constante e recuse timestamps distantes do horário atual. O guia de verificação mostra o tratamento completo do header.
Leia o corpo exatamente como chegou, antes do parser de JSON. Transformar o objeto de volta em JSON pode mudar espaços ou a ordem das chaves e quebrar a verificação. Valide o timestamp e o header, confira se os digests têm o mesmo tamanho e compare em tempo constante. Só depois interprete o JSON.
O trecho abaixo pressupõe que t e v1 já foram extraídos e validados. Na documentação, os exemplos completos em Node.js e Python usam tolerância de 5 minutos. Use o segredo inteiro, incluindo whsec_. Se você trocar o segredo da equipe, as próximas entregas já usam o novo.
const expected = crypto
.createHmac('sha256', secret)
.update(`${t}.${rawBody}`)
.digest('hex');
const valid = v1.length === expected.length
&& crypto.timingSafeEqual(Buffer.from(v1), Buffer.from(expected));Teste falhas e entregas repetidas antes de publicar
Teste um evento de conclusão, um de falha e uma entrega duplicada. Confirme que a mesma conclusão não publica duas vezes e que uma falha não tenta publicar uma transcrição inexistente. Teste também a recusa de uma assinatura inválida, separada dos erros da sua aplicação.
Cada entrega espera até 10 segundos pela resposta. Não aguarde indexação ou chamadas lentas de IA antes de confirmar o recebimento. Use uma fila persistente na sua aplicação para repetir essas etapas depois. As novas tentativas do webhook não substituem essa fila.
Respostas fora de 2xx, falhas de conexão e timeouts provocam novas tentativas após 2, 4, 8, 16 e 32 minutos, até 6 no total. Não seguimos redirecionamentos. Registre o ID, o tipo de evento e o status da entrega para distinguir falha no receptor de falha na transcrição. Nunca registre o segredo de assinatura.
Se todas as tentativas falharem, consulte os IDs salvos pela API de transcrições. O webhook não deve ser o único registro de que a transcrição existe. Assim você investiga uma notificação ausente sem enviar a mídia de novo.