Entender a repetição e as falhas dos webhooks
Nem todo envio chega de primeira: o seu sistema pode estar fora do ar, lento ou recusando. Esta página descreve o que a iPORTO faz em cada caso — e o que acontece quando as tentativas acabam.
O que conta como sucesso
Seção intitulada “O que conta como sucesso”Só resposta 2xx. Qualquer outra, ou nenhuma resposta dentro de 15 segundos, é falha.
| Resposta do seu endereço | O que fazemos |
|---|---|
| 2xx | entrega concluída |
| 408, 429, 5xx, timeout, falha de DNS ou de TLS | nova tentativa |
| 3xx (redirecionamento) | falha definitiva — não seguimos redirecionamento; configure o endereço final |
| demais 4xx | falha definitiva: é recusa do seu lado, e repetir não muda o resultado |
As tentativas
Seção intitulada “As tentativas”São 6 tentativas, com esperas de 1, 5 e 30 minutos, 2 horas e 8 horas — uma janela de aproximadamente 10 horas e 36 minutos entre a primeira tentativa e a última.
O número da tentativa vem no cabeçalho X-iPORTO-Attempt, começando em 1. Esgotadas as
tentativas, a entrega é marcada como abandonada.
Quando o endereço é desativado
Seção intitulada “Quando o endereço é desativado”Dez entregas abandonadas consecutivas desativam o endereço, e você recebe um e-mail avisando.
Desativado, ele para de receber tudo — e os eventos ocorridos nesse período não são reenviados depois. A reativação é na tela do endpoint, no botão Reativar endpoint.
Uma entrega bem-sucedida zera o contador: dez falhas seguidas são necessárias.
Acompanhar cada disparo
Seção intitulada “Acompanhar cada disparo”No painel de e-mail (SMTP), em Webhook → Histórico de Disparos, você vê cada envio. Clicando em um disparo, o detalhe traz:
- os cabeçalhos que foram enviados;
- o corpo enviado;
- o código de resposta e o corpo que o seu sistema devolveu;
- o número de tentativas e o motivo da falha, quando houve.
O histórico é mantido por 7 dias.
Reenviar
Seção intitulada “Reenviar”O detalhe do disparo tem o botão Reenviar, que cria um envio novo — o registro do envio anterior é preservado. O reenvio vai para o endereço configurado hoje, não para o endereço que estava configurado quando o evento aconteceu.
É o caminho para confirmar uma correção no seu endpoint sem depender de uma mensagem nova.
Se der errado
Seção intitulada “Se der errado”| Sintoma | Causa provável | O que fazer |
|---|---|---|
| O histórico mostra abandonada em todos os disparos | O endereço não responde 2xx — fora do ar, erro no seu código, ou autorização recusando | Abra o detalhe do disparo e leia o corpo da resposta do seu sistema; é ele que diz o motivo |
| O histórico mostra falha com motivo de timeout | O processamento do seu lado passa de 15 segundos | Responda 2xx antes de processar |
| Os eventos pararam e chegou e-mail de aviso | Dez abandonos consecutivos desativaram o endereço | Corrija a causa e clique em Reativar endpoint; os eventos do período não são reenviados |
| Disparos com 4xx e sem nova tentativa | Recusa definitiva do seu lado — rota inexistente, autorização inválida, corpo recusado | Confira a rota e o token configurado em Método de Autorização |
| Disparos com 413 (corpo grande demais) | O seu servidor limita o tamanho do corpo, e o evento cresceu: todo corpo traz param.details |
Aumente o limite do seu servidor; ver O bloco param.details |
| O mesmo evento aparece em dois disparos | Você cadastrou mais de um endereço para o canal | É esperado: o X-iPORTO-Event-Id é o mesmo nos dois, e o X-iPORTO-Delivery é diferente |
| Um disparo antigo não oferece Reenviar | Disparos anteriores à versão atual do histórico não têm o registro necessário para repetir o envio | O detalhe explica o motivo na própria tela |