Como funciona o recebimento automático de notas via webhook
· 6 min de leitura
O webhook de recebimento automático segue um fluxo simples: um evento é gerado quando a nota chega, um payload com os dados é enviado para o endpoint configurado, e o sistema que recebe confirma o recebimento.
Evento de nova nota
Assim que uma nota de serviço é identificada no monitoramento, um evento é gerado (tipicamente algo como “nota recebida”) e o sistema monitorado passa a tentar entregá-lo para a URL configurada por quem consome o webhook.
Payload enviado
O corpo da chamada costuma trazer o tipo do evento e os dados essenciais da nota, assinado digitalmente (HMAC) para que quem recebe possa confirmar que a chamada realmente veio do sistema esperado, e não de terceiros. Veja mais sobre essa validação em boas práticas de segurança em webhooks de documentos fiscais.
Confirmação de recebimento
O endpoint que recebe o webhook precisa responder com sucesso (normalmente um HTTP 200) para confirmar que processou a chamada. Sem essa confirmação, quem envia o webhook entende que a entrega falhou e tenta de novo; veja como isso funciona em como lidar com falhas e reentrega de webhook.
Perguntas frequentes
O sistema precisa responder ao webhook para confirmar o recebimento?
Sim: sem uma resposta de sucesso, quem envia o webhook não tem como saber se a chamada foi processada, e via de regra tenta reenviar. Responder rápido, mesmo que o processamento em si aconteça depois de forma assíncrona, evita reentregas desnecessárias.
O que acontece se meu endpoint estiver fora do ar quando a nota chegar?
Depende da política de reentrega de quem envia o webhook: a maioria reprocessa automaticamente por um período antes de desistir. Não é algo que você precisa resolver do seu lado além de ter um endpoint estável.
Se sua empresa quer ver exemplos práticos antes de implementar, veja casos de uso de webhook para recebimento fiscal automático. A IntegroBR NFS-e Recebidas já implementa esse fluxo completo (evento assinado, entrega e reentrega automática) para o período que você escolher monitorar.