Webhooks fiscais seguros: assinatura HMAC, retry e proteção contra SSRF
Boas práticas para receber eventos fiscais sem confiar cegamente na origem, duplicar processamento ou expor a rede interna.
Webhooks eliminam consultas repetitivas quando uma importação termina, uma análise crítica é criada ou uma integração fica offline. Eles também abrem uma porta HTTP no sistema receptor. Por isso, assinatura, idempotência e controle de destino precisam fazer parte do contrato.
Assina o corpo bruto
O emissor calcula HMAC-SHA256 do corpo com um segredo compartilhado e envia a assinatura no cabeçalho. O receptor calcula novamente usando exatamente os bytes recebidos e compara com função resistente a timing. Somente depois interpreta o JSON.
Evento não é comando irrepetível
Uma mesma entrega pode chegar mais de uma vez por causa de timeout ou retry. O receptor deve guardar o identificador do evento e ignorar repetições já processadas. O endpoint responde rápido e envia o trabalho para uma fila local.
Retentativa com intervalo
Falhas temporárias merecem nova tentativa; falhas permanentes não devem gerar tráfego infinito. Uma política progressiva pode tentar após 1, 5 e 15 minutos e depois 1 hora, com limite total. Falhas consecutivas ficam visíveis e podem desativar a integração.
Proteção contra SSRF
Ao cadastrar a URL, o servidor valida HTTPS, host, porta e resolução DNS. Endereços privados, loopback e redes reservadas são bloqueados. Redirecionamentos não devem permitir escapar dessa política.
Segredo e rotação
O segredo aparece somente quando criado e fica armazenado de forma protegida. A interface precisa permitir substituir ou revogar uma integração. Logs mostram apenas identificação parcial.
Observabilidade
Registra tentativa, status HTTP, duração, próximo retry e trecho seguro do erro. Um botão de teste ajuda a validar o receptor antes de ativar eventos reais.
Webhook confiável não é apenas um POST automático. É um canal autenticado, repetível e observável entre sistemas.
Observabilidade da entrega
Cada tentativa deve registrar evento, destino, horário, código HTTP, latência e próxima execução, sem gravar segredos ou payload sensível em log. O painel mostra entregas pendentes e falhas permanentes e permite reprocessar somente o necessário. Assim, integração assíncrona deixa de ser uma caixa-preta para suporte e operação.