HMAC e hashing para assinaturas de API: protegendo webhooks

Quando um serviço de terceiros envia dados via webhook ou você precisa autenticar uma solicitação de API, você precisa encontrar uma maneira de provar que a mensagem não foi adulterada e realmente veio de quem diz que foi. Hashing sozinho não resolve isso; você precisa do HMAC. Compreender a diferença entre um hash simples e um HMAC e como verificar as assinaturas corretamente é a diferença entre uma integração segura e uma integrada.

O que é um hash

Um hash é uma função unidirecional que transforma qualquer entrada – texto, um arquivo, uma resposta de API – em uma string de comprimento fixo. A mesma entrada sempre produz a mesma saída. Algoritmos de hash comuns incluem SHA-256, SHA-1 e MD5. Você pode usar um gerador de hash para ver isso em ação: "hello" sempre se torna o mesmo hash SHA-256. A propriedade principal é que o hash é determinístico, mas impossível de ser revertido; você não pode recuperar a entrada original do hash.

O que é HMAC

HMAC significa Código de Autenticação de Mensagem Baseado em Hash. Ao contrário de um hash simples, o HMAC combina uma mensagem com uma chave secreta antes do hash. O provedor de webhook tem uma chave secreta, faz o hash da mensagem com essa chave e envia a mensagem e o hash para você. Você repete o processo com a mesma chave secreta; se o hash calculado corresponder ao enviado, você sabe que a mensagem é autêntica e não modificada. O Gerador HMAC ferramenta permite testar isso com sua própria mensagem e segredo.

A diferença crítica: hash vs HMAC

Veja por que isso é importante:

• Hash simples: Qualquer pessoa pode ver sua mensagem e recalcular o hash para forjar uma mensagem “válida”. Isso não prova nada.
• HMAC: Somente alguém com a chave secreta pode produzir o HMAC correto. Prova criptograficamente que a mensagem veio do detentor da chave e não foi alterada.

Se um serviço enviar a você um webhook apenas com um hash, um invasor poderá interceptá-lo, alterar os dados, recalcular o hash e você não perceberá. Com o HMAC e um segredo compartilhado, o invasor não pode falsificar uma assinatura válida sem a chave.

Verificando assinaturas de webhook em seu código

Quando um webhook chega, o serviço fornece a carga útil da mensagem e um cabeçalho de assinatura (geralmente X-Signature ou X-Webhook-Signature). Seu código deve:

1. Recupere sua chave secreta da configuração segura (variáveis de ambiente, um gerenciador de segredos).
2. Calcule o HMAC-SHA256 do corpo da solicitação bruta usando essa chave.
3. Compare seu HMAC calculado byte por byte com o cabeçalho da assinatura (sempre use comparação de tempo constante para evitar ataques de temporização).
4. Se corresponderem, o webhook é autêntico. Se não, rejeite-o.

A maioria dos provedores de webhook documenta seu algoritmo HMAC e o formato exato para assinar – às vezes é o corpo JSON bruto, às vezes um carimbo de data/hora concatenado com o corpo. Siga exatamente as especificações deles.

HMAC vs JWT: onde eles se encaixam

JWTs (JSON Web Tokens) são frequentemente confundidos com assinaturas HMAC. Um JWT é um token independente com três partes: um cabeçalho, uma carga útil (declarações) e uma assinatura. A assinatura pode ser baseada em HMAC ou RSA. Decodificadores JWT permitem inspecionar e verificar tokens. Embora os HMACs verifiquem uma única mensagem, os JWTs são tokens que você armazena e envia com cada solicitação ou chamada de API. Para webhooks e autenticação de mensagens únicas, o HMAC é mais simples e suficiente. Para tokens de sessão contínua ou credenciais de API, um JWT costuma ser mais flexível.

Privacidade: assine e verifique inteiramente no seu navegador

As ferramentas HMAC e hash do TextArray são executadas inteiramente no seu navegador. Nenhuma mensagem, segredo ou assinatura é carregada em um servidor. Nenhuma conta é necessária e as ferramentas funcionam offline após o carregamento da página. Você pode colar com segurança cargas úteis de webhook e chaves de API para testar e depurar assinaturas sem expor dados a terceiros ou a serviços de registro. Isso é especialmente valioso quando você trabalha com chaves de API confidenciais ou dados de clientes durante o desenvolvimento.

Começando

Comece entendendo o hash: use o gerador de hash para ver como a mesma entrada sempre produz a mesma saída SHA-256. Então vá para Geração HMAC para ver como uma chave secreta altera a saída. Tente alterar ligeiramente a chave ou a mensagem; o HMAC muda completamente, ao contrário de uma soma de verificação ingênua. Depois de entender a mecânica, aplique-a à lógica de verificação do webhook. Para cargas sensíveis como texto criptografado ou tokens decodificados, sempre combine-os com solicitações assinadas pelo HMAC para garantir a integridade e a origem.