Erros comuns ao configurar webhook de NF-e e CT-e
· 5 min de leitura
Configurar um webhook de NF-e ou CT-e parece simples, mas alguns erros recorrentes fazem eventos serem perdidos ou tratados errado do lado de quem recebe. Veja os mais comuns.
Assinar só um tipo de evento e assumir que cobre tudo
Assinar apenas o evento de NF-e recebida não traz eventos de CT-e, e vice-versa: cada tipo de documento tem seu próprio evento, como visto em webhook para NF-e e CT-e. Um erro comum é configurar o webhook pensando só no documento que motivou a integração (geralmente NF-e) e esquecer de assinar o CT-e quando ele também é relevante.
Não validar a assinatura HMAC
Aceitar qualquer payload recebido na URL do webhook, sem validar a assinatura, abre espaço para que uma requisição forjada seja tratada como um documento fiscal real. A validação da assinatura é o que garante que o payload realmente veio da IntegroBR, não de terceiros.
Não tratar reentrega
Uma falha temporária no endpoint (timeout, erro 500) leva a uma nova tentativa de entrega. Se o processamento do lado de quem recebe não for idempotente, o mesmo documento pode acabar sendo processado mais de uma vez. Usar a chave de acesso do documento como identificador de deduplicação evita esse problema.
Não monitorar falhas de entrega
Se o endpoint fica fora do ar por um período e as tentativas de reentrega se esgotam sem sucesso, o documento nunca chega. Sem um alerta próprio para isso, essa falha só é percebida quando alguém nota a ausência do documento por outro caminho, tarde demais para agir a tempo.
Perguntas frequentes
Um webhook com falha constante afeta outros webhooks da mesma conta?
Não. Cada webhook cadastrado tem sua própria fila de entrega e histórico de tentativas, independente dos demais.
Detalhes de payload, tentativas de reentrega e assinatura estão na documentação da API pública.