HMAC em webhooks

O que significa HMAC?

HMAC é a sigla em inglês para código de autenticação de mensagem baseado em hash. É um método que pega duas coisas, o conteúdo de uma mensagem e uma chave secreta, e as passa por uma função de hash, como o SHA-256. O resultado é uma sequência de caracteres de tamanho fixo, que funciona como uma assinatura.

Se uma única letra da mensagem mudar, ou se a chave usada for diferente, a assinatura gerada será completamente outra. Por isso, quem conhece a chave consegue verificar se a mensagem é autêntica e está íntegra.

Para que serve o HMAC em webhooks?

Webhook é uma notificação que um sistema envia automaticamente para outro quando algo acontece. Em uma API fiscal, por exemplo, o emissor avisa o ERP do cliente que uma NF-e foi autorizada, que uma NFS-e foi rejeitada ou que um cancelamento foi concluído.

O problema é que o endereço que recebe essas notificações fica exposto na internet. Sem proteção, qualquer pessoa poderia enviar uma mensagem falsa dizendo que uma nota foi autorizada. O HMAC resolve isso: o sistema só aceita a notificação se a assinatura que veio junto bater com a que ele mesmo calcula usando a chave secreta.

Como funciona a validação da assinatura?

Antes de tudo, quem envia e quem recebe combinam uma chave secreta, que nunca trafega junto com as notificações. Quando um evento acontece, o remetente calcula o HMAC do corpo da mensagem com essa chave e envia o resultado em um cabeçalho HTTP da requisição.

Ao receber, o sistema do cliente pega o corpo exatamente como chegou, calcula o HMAC com a mesma chave e compara com o valor do cabeçalho. Se forem iguais, a mensagem é legítima e pode ser processada. Se forem diferentes, a notificação deve ser descartada e, de preferência, registrada em log para investigação.

Qual a diferença entre HMAC e assinatura digital?

A assinatura digital, como a usada no XML de uma NF-e, utiliza um par de chaves: uma privada, que assina, e uma pública, que qualquer pessoa pode usar para conferir. Ela prova a autoria perante terceiros e tem validade jurídica quando feita com certificado digital.

O HMAC usa uma única chave secreta, conhecida pelas duas partes. É mais simples e rápido, ideal para comunicação entre dois sistemas que confiam um no outro, mas não serve para provar a autoria para um terceiro, já que ambos os lados poderiam ter gerado a assinatura. Também é diferente de um hash simples, que não usa chave e, portanto, pode ser recalculado por qualquer um.

Quais cuidados tomar ao implementar HMAC em webhooks?

Calcule a assinatura sobre o corpo bruto da requisição, antes de convertê-lo em objeto JSON, pois reformatar espaços ou a ordem dos campos muda o resultado. Use uma função de comparação em tempo constante, disponível na maioria das linguagens, para evitar ataques que exploram o tempo de resposta.

Guarde a chave secreta em um cofre ou gerenciador de segredos, nunca no código-fonte, e troque-a periodicamente. Quando houver um carimbo de data e hora na mensagem, recuse notificações muito antigas para impedir que alguém reenvie uma mensagem verdadeira capturada antes. E mantenha o endpoint em HTTPS, já que o HMAC garante autenticidade, mas não esconde o conteúdo.

Exemplos de HMAC em webhooks

• Um ERP recebe um webhook informando que a NF-e de um pedido foi autorizada, recalcula o HMAC-SHA256 do corpo com a chave secreta configurada e, como o valor confere, atualiza o pedido para faturado e baixa o XML.
• Uma plataforma de vendas recebe uma notificação de cancelamento de NFC-e cuja assinatura não confere; o sistema descarta a mensagem, registra o incidente em log e consulta o status diretamente na API para confirmar a situação real.
• Um marketplace troca a chave secreta dos webhooks por política de segurança e, durante um período de transição, aceita assinaturas geradas com a chave antiga e com a nova até concluir a migração.
• Uma transportadora valida o HMAC das notificações de autorização de CT-e e MDF-e antes de liberar a viagem no seu software de gestão.