Webhooks: Assinatura HMAC, Reentregas e Boas Práticas
Como receber o resultado das transcrições por webhook: assinatura HMAC-SHA256, headers X-VPT-Signature e X-VPT-Event, 6 tentativas de reentrega com backoff.
Em vez de ficar consultando a API para saber se a transcrição terminou, você informa um webhook_url na requisição e o VozParaTexto envia um POST para o seu servidor quando o trabalho conclui — com sucesso ou com erro. É o jeito recomendado de integrar: gasta menos requisições e o resultado chega na hora.
Como funciona
- Você envia o áudio com um
webhook_url(obrigatoriamentehttps). - Quando o processamento termina, fazemos um POST para essa URL com o resultado.
- Seu servidor responde com um status
2xxpara confirmar o recebimento.
Cada entrega leva dois headers de identificação:
| Header | Conteúdo |
|---|---|
X-VPT-Event | O tipo do evento (conclusão, falha etc.) |
X-VPT-Signature | Assinatura HMAC-SHA256 da entrega |
Sempre valide a assinatura antes de confiar no conteúdo: calcule o HMAC-SHA256 do corpo recebido e compare com o valor do header X-VPT-Signature. Requisição sem assinatura válida deve ser descartada — qualquer um pode descobrir a URL do seu endpoint.
Reentregas automáticas
Se o seu endpoint estiver fora do ar ou demorar demais, nós tentamos de novo:
- Timeout por tentativa: 15 segundos.
- Máximo de tentativas: 6.
- Espera entre tentativas (backoff): 5 min → 30 min → 2 h → 6 h → 24 h.
Todas as entregas ficam persistidas no nosso lado, então é possível auditar o histórico com o suporte se algo se perder.
Responda o webhook imediatamente com 200 e processe o conteúdo de forma assíncrona (fila, job). Se o seu processamento demorar mais de 15 segundos, a entrega conta como falha e entra na fila de reentrega — e você pode acabar recebendo o mesmo evento duas vezes. Trate os eventos de forma idempotente.
Você sempre recebe um desfecho
Jobs que travam não somem em silêncio:
- Job na fila parado há mais de 10 minutos é reenfileirado automaticamente.
- Job em processamento travado há mais de 60 minutos é marcado como falho — e dispara um webhook de erro para a sua URL.
Ou seja: para cada áudio enviado, o seu sistema recebe um callback final, de sucesso ou de falha.
FAQ
Meu servidor ficou fora do ar. Perdi o resultado?
Provavelmente não: são até 6 tentativas distribuídas ao longo de ~24 horas. Se todas falharem, o histórico de entregas fica registrado — fale com o suporte para reprocessar.
Posso usar uma URL http (sem TLS)?
Não. Por segurança, só aceitamos URLs https, sem redirecionamentos, e endereços internos/privados são bloqueados.
Como diferencio um webhook de sucesso de um de erro?
Pelo header X-VPT-Event, que identifica o tipo do evento, e pelo conteúdo do corpo da entrega.
O que meu endpoint precisa responder?
Qualquer status 2xx dentro de 15 segundos. Outros status (ou timeout) contam como falha e geram reentrega.
Artigos relacionados
Não resolveu? Abra um ticket — nossa equipe responde rápido.