Como calcular assinaturas HMAC
Assine requisições de API com segredo compartilhado, depure payloads de webhook e verifique assinaturas ao estilo Stripe/GitHub/AWS com o algoritmo HMAC e formato de digest corretos.
Mais utilitários que combinam com este guia:
Por que isso importa
Webhooks são como a nuvem fala de volta. Stripe avisa quando um pagamento cai; GitHub quando sai um release. Para provar autenticidade, o remetente envia uma assinatura HMAC sobre o corpo com um segredo compartilhado. Se seu verificador rejeita tudo, você não sabe se o segredo, o algoritmo ou um proxy alterando o corpo está errado. Uma ferramenta HMAC lado a lado com pré-visualização do input reduz o ciclo de depuração de horas para minutos.
Três cenários reais
Cole payload, segredo e timestamp; calcule HMAC-SHA-256; compare com o cabeçalho Stripe-Signature.
Handler de webhook entrega
Monte a string canônica, assine HMAC com o segredo compartilhado, anexe como cabeçalho.
Chamada aceita
Use inputs de exemplo do fornecedor; se não bater, a doc pode estar errada.
Docs confirmadas
Passo a passo
Abra o gerador HMAC.
Cole a mensagem
Os bytes exatos assinados — normalmente o corpo HTTP bruto. Atenção a diferenças de espaço em branco.
Cole a chave secreta
Strings são UTF-8 por padrão. Ative “segredo é hex” ou “segredo é Base64” se o fornecedor distribuir chaves binárias.
Escolha o hash
SHA-256 é o padrão moderno; SHA-1 ainda aparece em sistemas antigos; SHA-512 é raro mas suportado.
Escolha o formato de saída
Hex minúsculo é comum em cabeçalhos. Base64 é exigido em AWS Sig V4 e algumas APIs.
Compare com a assinatura recebida
Cole o valor do cabeçalho. A ferramenta destaca coincidências e divergências caractere a caractere.
Entradas
Message: t=1731234567.{"id":"evt_123","type":"payment_intent.succeeded"}
Secret: whsec_abc123xyz
Algorithm: SHA-256HMAC-SHA-256 hex
4ed7a40c1e1f9c0bba9d7c1f24eb44a3f0bd06d0c81bd5d4a7f6cf52a6f00f1e
Dicas avançadas
- Diff no corpo antes de assinar. Muitas falhas vêm de proxy adicionando newline final. A assinatura é sobre os bytes exatos — um
\na mais importa. - Use comparação em tempo constante no servidor. Isso é papel do seu código, não só da ferramenta no navegador.
- Rotacione segredos sem downtime aceitando duas chaves válidas por um período. A ferramenta ajuda a conferir ambas antes de desativar a antiga.
- Documente a string canônica. AWS Sig V4 concatena método, caminho, cabeçalhos e hash do corpo; reproduza manualmente uma vez para validar a fórmula.
Armadilhas comuns
Erro comum
Diferença de uma newline final
O corpo no seu IDE tem \n final; o enviado pela rede não. Remova espaços conforme o verificador — mas exatamente como ele faz.
Erro comum
Segredo interpretado com encoding errado
Alguns enviam chaves como Base64; o HMAC usa os bytes decodificados, não os caracteres ASCII. Ajuste o toggle do encoding à doc do fornecedor.
Erro comum
BOM UTF-8 escondido no payload
A sequência inicial EF BB BF muda o hash. Use visualizador hex se assinaturas falharem “sem motivo”.
Quando esta não é a ferramenta certa
- Assinaturas de chave pública (RSA, ECDSA, Ed25519) — outro fluxo. Veja Como verificar assinaturas digitais online.
- Criptografia simétrica — HMAC autentica, não cifra. Para confidencialidade + autenticidade, AES-GCM.
- Hash de senha — nunca use HMAC para armazenar senhas. Use KDF lenta.
FAQ
E se minha chave for menor que o bloco?
O HMAC trata internamente. Não precisa pad manual.
Assino antes ou depois de formatar JSON?
Sempre depois da forma canônica estar fixa. Reformatar depois quebra a assinatura.
Algo vai para um servidor?
Não. O HMAC é calculado no navegador via WebCrypto.
Próximos passos
- Faça hash do corpo separadamente com o gerador de hash quando o protocolo pedir
body_hashantes do HMAC. - Monte assinatura completa da requisição com a ferramenta Assinatura de parâmetros.
- Decodifique JWTs relacionados com Codificar/decodificar — JWTs HS usam HMAC.