Retentativas
Política de retentativas, backoff exponencial e boas práticas para garantir a entrega confiável de webhooks.
Política de retentativas
Se o seu servidor não responder com um status HTTP 2xx, a SoarLabz reenvia a notificação automaticamente com backoff exponencial.
| Tentativa | Atraso | Tempo acumulado |
|---|---|---|
| 1a | 30 segundos | 30s |
| 2a | 1 minuto | 1min 30s |
| 3a | 5 minutos | 6min 30s |
| 4a | 15 minutos | 21min 30s |
| 5a | 30 minutos | 51min 30s |
| 6a | 1 hora | 1h 51min |
| 7a | 2 horas | 3h 51min |
| 8a | 4 horas | 7h 51min |
| 9a | 8 horas | 15h 51min |
| 10a | 24 horas | ~40h |
Após 10 tentativas sem sucesso, a entrega é marcada como exhausted (esgotada) e não será mais reenviada. O ciclo completo de retentativas cobre aproximadamente 40 horas.
Status de entrega
| Status | Descrição |
|---|---|
pending | Entrega pendente (aguardando envio) |
success | Entregue com sucesso (resposta 2xx) |
failed | Falha na entrega (será retentada) |
exhausted | Todas as tentativas esgotadas |
Resposta esperada
Sua aplicação deve:
- Responder com status HTTP
2xx(200, 201, 202, etc.) - Responder em até 10 segundos — após esse tempo, a requisição é abortada e a tentativa marcada como falha
- Retornar o mais rápido possível
Não processe a lógica de negócios antes de responder ao webhook. Responda 200 OK imediatamente e processe o evento de forma assíncrona.
Boas práticas
Idempotência
O mesmo evento pode ser entregue mais de uma vez (em caso de timeout ou falha de rede). Use o campo id do payload como chave de idempotência para evitar processamento duplicado.
Tempo de resposta
Mantenha o tempo de resposta abaixo de 5 segundos. Se o processamento do evento é demorado:
- Salve o evento em uma fila ou banco de dados
- Responda
200 OKimediatamente - Processe o evento em background
Verificação de assinatura
Sempre valide a assinatura HMAC antes de processar qualquer evento. Isso garante que a notificação veio da SoarLabz e não foi adulterada.
Monitoramento
Monitore falhas de entrega. Se muitas notificações estão falhando, verifique:
- Se a URL está acessível publicamente
- Se o certificado SSL é válido
- Se o servidor responde em menos de 10 segundos
- Se o firewall permite conexões da SoarLabz