Boas práticas de segurança em webhooks de documentos fiscais
· 5 min de leitura
Como o endpoint que recebe um webhook fica exposto na internet, ele precisa de cuidados de segurança específicos, afinal, o que chega ali carrega dados fiscais reais da empresa.
Validação de assinatura
A prática mais importante é verificar a assinatura digital (normalmente HMAC) enviada junto com a chamada, calculando o hash esperado com uma chave compartilhada e comparando com o que veio no cabeçalho da requisição. Sem essa validação, qualquer chamada formatada corretamente para aquela URL seria aceita como se fosse legítima.
Uso de HTTPS
O endpoint precisa aceitar apenas conexões HTTPS: um webhook trafegando em texto puro expõe os dados fiscais da nota a qualquer um capaz de interceptar a conexão. Isso é básico, mas ainda aparece como falha em integrações configuradas às pressas.
Registro de eventos recebidos
Manter um log de cada webhook recebido (mesmo que rejeitado por assinatura inválida) ajuda a identificar tanto problemas de configuração legítimos quanto tentativas de chamadas maliciosas para aquele endpoint.
Perguntas frequentes
Como saber se um webhook recebido é legítimo?
Validando a assinatura digital contra a chave compartilhada configurada: se a assinatura não bater, a chamada deve ser rejeitada, mesmo que o conteúdo pareça correto. Nunca confie apenas na estrutura do payload para decidir se um webhook é confiável.
É preciso responder rápido mesmo durante a validação de segurança?
Sim, validar a assinatura deve ser rápido, e o processamento pesado do conteúdo pode acontecer depois, de forma assíncrona. Veja como isso se conecta com a política de reentrega de quem envia o webhook.
Para outras dúvidas técnicas sobre webhook, veja o FAQ técnico completo sobre webhook de NFS-e.
Cada webhook disparado pela IntegroBR NFS-e Recebidas já vem assinado digitalmente, para que seu endpoint possa validar a origem antes de confiar no conteúdo.