Webhook falhou — reenvio e diagnóstico
Webhook falhou — veja como identificar a causa, reenviar manualmente e configurar retry.
Onde acessar
Loja > Configurações > Webhooks > [webhook] > Log de entregasComo identificar uma falha
O log de entregas mostra cada tentativa de envio com:
- Status HTTP da resposta do servidor de destino
- Payload enviado (evento + dados)
- Timestamp da tentativa
- Resposta retornada pelo servidor de destino
Uma entrega com status diferente de 2xx (ex: 4xx, 5xx, timeout) é considerada falha.
Status mais comuns e o que significam
| Status | Causa | Ação | |---|---|---| | `200 OK` | Entregue com sucesso | Nenhuma | | `401 Unauthorized` | Secret incorreto no servidor de destino | Verificar secret no sistema externo | | `404 Not Found` | URL do endpoint não existe mais | Atualizar URL do webhook | | `422 Unprocessable` | Payload inválido — sistema externo não entende o formato | Verificar versão da API ou mapeamento | | `500 Internal Error` | Erro no servidor de destino | Aguardar e fazer retry manual | | `Timeout` | Servidor de destino demorou mais de 10s para responder | Otimizar o endpoint de destino ou usar fila assíncrona |
Como reenviar um evento manualmente
- Acesse Loja > Configurações > Webhooks > [webhook] > Log de entregas
- Localize o evento que falhou
- Clique em Reenviar
- O sistema envia o payload original novamente para a mesma URL
O reenvio manual envia o payload exatamente como era na tentativa original — incluindo o timestamp do evento original.
Configuração de retry automático
Por padrão, a evob tenta reenviar webhooks com falha com backoff exponencial:
| Tentativa | Intervalo | |---|---| | 1ª | Imediata | | 2ª | 5 minutos | | 3ª | 30 minutos | | 4ª | 2 horas | | 5ª | 24 horas |
Após 5 tentativas sem sucesso, o webhook é marcado como "Abandonado" e não há novo retry automático. Reenvio manual continua disponível.
Boas práticas
✅ Faça
- Configure o endpoint de destino para responder em menos de 5 segundos — use uma fila (SQS, RabbitMQ) para processar de forma assíncrona sem risco de timeout
- Monitore o log de webhooks semanalmente — falhas acumuladas podem indicar que a integração está desatualizada
- Use o secret HMAC para validar que os eventos recebidos vêm genuinamente da evob — rejeite eventos sem assinatura válida
❌ Não faça
- Ignorar status 422 assumindo que é problema da evob — geralmente indica que a versão do payload mudou e o parser do sistema externo precisa ser atualizado
- Criar múltiplos webhooks para o mesmo evento como fallback — gera duplicação de dados no sistema externo
- Usar URLs de desenvolvimento (localhost, ngrok gratuito com URL aleatória) em produção — a URL muda e o webhook passa a falhar silenciosamente
Erros comuns
"O webhook está configurado mas nunca chega no sistema externo"
Verifique se a URL do endpoint é acessível publicamente — `localhost` e URLs internas de rede corporativa não são acessíveis pelo servidor da evob. Use um serviço como ngrok ou um endpoint em servidor público para testes.
"O webhook chegou no sistema externo mas os dados estão incompletos"
Verifique qual versão da API o webhook usa. Em Webhooks > [webhook] > Configurações, confirme a versão do payload selecionada. Se o sistema externo espera a v2 e o webhook está na v1, os campos podem diferir.
"Recebo duplicatas do mesmo evento"
Isso pode acontecer quando o retry automático reenvia eventos que já foram processados mas o servidor demorou para responder (timeout). Implemente idempotência no endpoint usando o campo `event_id` do payload — descarte eventos com ID já processado.
"O log mostra sucesso mas o sistema externo não registrou o evento"
O sucesso no log significa que o servidor de destino respondeu 2xx. O problema está no processamento interno do sistema externo após receber o evento. Verifique os logs do sistema de destino.
Próximos passos
- 📖 Erro 401 — sem permissão
- 📖 Enviar evidências para o CS
- 📖 Quando abrir chamado com CS
- 📖 Integrações via Webhook
Foi útil este artigo? 👍 👎 Falar com CS (em produção) · Pergunte ao Vob 🤖 (em produção) Última atualização: 2026-05-06