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 ficares a consultar a API para saber se a transcrição terminou, informas um webhook_url no pedido e o VozParaTexto envia um POST para o teu servidor quando o trabalho termina — com sucesso ou com erro. É a forma recomendada de integrar: gasta menos pedidos e o resultado chega na hora.
Como funciona
- Envias o áudio com um
webhook_url(obrigatoriamentehttps). - Quando o processamento termina, fazemos um POST para essa URL com o resultado.
- O teu servidor responde com um status
2xxpara confirmar a receção.
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 |
Valida sempre a assinatura antes de confiares no conteúdo: calcula o HMAC-SHA256 do corpo recebido e compara com o valor do header X-VPT-Signature. Um pedido sem assinatura válida deve ser descartado — qualquer pessoa pode descobrir a URL do teu endpoint.
Reentregas automáticas
Se o teu endpoint estiver fora do ar ou demorar demasiado, 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 do nosso lado, por isso é possível auditar o histórico com o suporte se algo se perder.
Responde ao webhook imediatamente com 200 e processa o conteúdo de forma assíncrona (fila, job). Se o teu processamento demorar mais de 15 segundos, a entrega conta como falha e entra na fila de reentrega — e podes acabar por receber o mesmo evento duas vezes. Trata os eventos de forma idempotente.
Recebes sempre um desfecho
Jobs que travam não desaparecem 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 tua URL.
Ou seja: para cada áudio enviado, o teu sistema recebe um callback final, de sucesso ou de falha.
FAQ
O 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 registado — fala 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 o meu endpoint precisa de responder?
Qualquer status 2xx dentro de 15 segundos. Outros status (ou timeout) contam como falha e geram reentrega.
Artigos relacionados
Não resolveste? Abre um ticket — a nossa equipa responde depressa.