# Webhook de transcrição para receber a conclusão ou falha

> Configure um webhook de transcrição com webhook_url. Receba um POST assinado quando ela terminar ou falhar, sem consultar o status repetidamente.

Canonical: https://transcript1.com/pt/features/webhook-transcricao
Language: pt-BR
Last updated: 2026-10-19

Adicione um webhook de transcrição com webhook_url ao criar uma transcrição. Quando ela terminar ou falhar, enviamos um POST assinado para seu endpoint. Seu código recebe o evento sem precisar consultar o status repetidamente.

- Eventos transcription.completed e transcription.failed
- Assinatura HMAC-SHA256 em cada entrega
- Até 6 tentativas, com intervalos progressivos

## Receba o evento e busque a transcrição pelo ID

### Conclusão e falha têm eventos próprios

Receba transcription.completed ou transcription.failed. Se você cancelar a transcrição, não enviamos webhook.

### Confira quem enviou a chamada

O header X-Transcript1-Signature inclui um timestamp e a assinatura HMAC-SHA256 do corpo original, calculada com o segredo whsec_ da equipe.

### Tentamos de novo se a entrega falhar

Qualquer resposta 2xx confirma a entrega. Caso contrário, esperamos 2, 4, 8, 16 e 32 minutos entre as novas tentativas, até completar 6 no total.

### Destino público com HTTPS

A URL precisa usar HTTPS e apontar para um endereço público. Conferimos isso ao criar a transcrição e em cada entrega.

### O evento leva o ID, não o texto completo

O payload inclui o objeto da transcrição sem o texto transcrito. Use o ID para buscar o formato de que sua aplicação precisa.

## 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](https://transcript1.com/pt/docs/webhooks#set-a-webhook-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.

### Upload com notificação por webhook

```
curl -X POST "https://api.transcript1.com/v1/transcriptions" \
  -H "Authorization: Bearer $TRANSCRIPT1_API_KEY" \
  -F file=@episode.mp3 \
  -F webhook_url=https://example.com/hooks/transcript1
```

## Registre 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](https://transcript1.com/pt/docs/api-reference#get-a-transcription).

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.

### POST enviado ao seu endpoint

```
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](https://transcript1.com/pt/docs/webhooks#verify-the-signature) 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.

### Node.js

```
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));
```

- [Exemplos completos de verificação da assinatura](https://transcript1.com/pt/docs/webhooks)

## 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](https://transcript1.com/pt/docs/api-reference#get-a-transcription). 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.

## Dúvidas frequentes

### Onde encontro o segredo de assinatura?

Na página “Webhooks” do painel. Ele começa com whsec_, pertence à equipe e pode ser trocado nessa página a qualquer momento.

### O que acontece se meu endpoint não responder?

Tentamos entregar de novo com intervalos progressivos: até 6 tentativas no total, ao longo de cerca de uma hora. Cada tentativa tem timeout de 10 segundos. Não seguimos redirecionamentos.

### Posso usar webhooks pelo MCP?

Não. Webhooks estão disponíveis só na API REST. Pelo MCP, a ferramenta espera pela transcrição ou retorna um ID para consultar depois.

## Veja também

- [Receba avisos por webhook (docs)](https://transcript1.com/pt/docs/webhooks)
- [API para arquivos](https://transcript1.com/pt/features/speech-to-text-api)
- [Agentes de IA](https://transcript1.com/pt/use-cases/transcricoes-para-agentes-de-ia)