Como lidar com falhas e reentrega de webhook de NFS-e
· 6 min de leitura
Nenhum webhook chega com 100% de garantia na primeira tentativa: o endpoint pode estar fora do ar, a rede pode falhar, o processamento pode demorar demais. Uma implementação madura de webhook trata esses casos com reentrega automática, não com perda silenciosa do evento.
Motivos comuns de falha
O endpoint pode estar temporariamente indisponível, responder devagar demais (timeout), ou devolver um erro por estar sobrecarregado no momento. Também é comum a falha ser do lado de quem recebe: um deploy em andamento, uma instabilidade pontual, nada relacionado à nota em si.
Política de reentrega
Quando a entrega falha, o padrão é tentar de novo depois de um intervalo (geralmente crescente entre uma tentativa e outra) até um limite de tentativas antes de considerar o evento como não entregue. Isso é o que separa um webhook confiável de um que perde eventos silenciosamente na primeira falha.
Monitoramento de falhas
Do lado de quem recebe, vale monitorar quando o próprio endpoint está falhando: se o problema for recorrente, mais reentregas não resolvem a causa raiz. Do lado de quem consulta, veja também por que combinar webhook com uma verificação periódica ajuda a pegar qualquer evento que, mesmo com reentrega, não tenha sido processado.
Perguntas frequentes
Quantas tentativas de reentrega são consideradas razoáveis?
Não há um número universal: depende de quanto tempo faz sentido esperar antes de desistir. É comum um esquema de poucas tentativas nos primeiros minutos e, depois, tentativas mais espaçadas por um período maior, até um limite total razoável.
Como recuperar um evento que esgotou todas as tentativas de reentrega?
Depende de quem envia o webhook oferecer alguma forma de consulta manual do evento perdido, por isso vale, sempre que possível, também poder consultar a nota diretamente, sem depender só do webhook.
Veja também exemplos práticos de uso em casos de uso de webhook para recebimento fiscal automático. Os webhooks disparados pela IntegroBR NFS-e Recebidas já contam com reentrega automática em caso de falha: você não precisa implementar essa lógica do seu lado.