Cómo calcular firmas HMAC
Firma peticiones API con un secreto compartido, depura webhooks y verifica firmas al estilo Stripe / GitHub / AWS con el algoritmo HMAC y el formato de digest correctos.
Más utilidades que combinan bien con esta guía:
Por qué importa
Los webhooks son cómo la nube te responde. Stripe avisa cuando entra un pago; GitHub cuando hay un release. Para demostrar que el mensaje es auténtico, el emisor incluye una firma HMAC sobre el cuerpo con un secreto compartido. Si tu verificador rechaza todas las firmas, no sabes si falló el secreto, el algoritmo o si un proxy alteró el cuerpo. Una herramienta HMAC lado a lado con vista previa acorta el ciclo de depuración de horas a minutos.
Tres escenarios reales
Pega el payload, el secreto y la marca de tiempo; calcula HMAC-SHA-256; compara con la cabecera Stripe-Signature.
Handler de webhook listo
Construye la cadena canónica, firma con HMAC y el secreto, adjunta como cabecera.
Llamada aceptada
Usa las entradas de muestra del proveedor, calcula, compara. Si no coincide, la documentación del proveedor está mal.
Documentación confirmada
Guía paso a paso
Abre el generador HMAC.
Pega el mensaje
Los bytes exactos firmados — normalmente el cuerpo HTTP crudo. Ojo con diferencias de espacios en blanco.
Pega la clave secreta
Por defecto las cadenas se interpretan como UTF-8. Activa «secreto en hex» o «secreto en Base64» si el proveedor distribuye claves binarias.
Elige el algoritmo hash
SHA-256 es el estándar moderno; SHA-1 sigue en sistemas antiguos; SHA-512 es raro pero está soportado.
Elige el formato de salida
Hex (minúsculas) es lo habitual para cabeceras. Base64 lo exige AWS Sig V4 y algunas otras APIs.
Compara con la firma recibida
Pega el valor de la cabecera. La herramienta resalta coincidencias y diferencias carácter a carácter.
Entradas
Message: t=1731234567.{"id":"evt_123","type":"payment_intent.succeeded"}
Secret: whsec_abc123xyz
Algorithm: SHA-256HMAC-SHA-256 hex
4ed7a40c1e1f9c0bba9d7c1f24eb44a3f0bd06d0c81bd5d4a7f6cf52a6f00f1e
Consejos útiles
- Diff del cuerpo antes de firmar. Muchos fallos de webhook vienen de un proxy que añade un salto de línea final. La firma es sobre los bytes exactos.
- Usa siempre comparación en tiempo constante en el servidor. Eso es trabajo de tu código, no de la herramienta de firma en navegador.
- Rota secretos sin tiempo muerto permitiendo dos claves válidas un breve lapso. La herramienta ayuda a calcular ambas firmas antes de retirar la antigua.
- Documenta tu cadena canónica. Protocolos como AWS Sig V4 concatenan método, ruta, cabeceras y hash del cuerpo de forma específica; reprodúcela una vez con la herramienta para validar la fórmula.
Trampas comunes
Error frecuente
Desfase de un salto de línea final
Tu IDE tiene \n final; el cuerpo en red no. Elimina espacios antes de firmar — pero elimina exactamente lo que el verificador elimina.
Error frecuente
La clave se interpreta con codificación incorrecta
Algunos proveedores envían claves como Base64; HMAC debe usar los bytes decodificados, no los caracteres ASCII. Ajusta la codificación de entrada según la documentación.
Error frecuente
BOM UTF-8 oculto en el mensaje
La secuencia inicial EF BB BF cambia el hash. Abre la fuente en un visor hex si las firmas fallan «sin razón».
Cuándo no es la herramienta adecuada
- Firmas de clave pública (RSA, ECDSA, Ed25519) — necesitan otro verificador. Ver Cómo verificar firmas digitales en línea.
- Cifrado simétrico — HMAC autentica, no cifra. Usa AES-GCM si necesitas confidencialidad y autenticidad.
- Hash de contraseñas — nunca uses HMAC para almacenar contraseñas. Usa un KDF lento.
Preguntas frecuentes
¿Qué pasa si mi clave es más corta que el tamaño de bloque?
HMAC lo gestiona internamente. No necesitas rellenar la clave.
¿Debo firmar antes o después de formatear JSON?
Siempre después de fijar la forma canónica. Si reformateas después, la firma se rompe.
¿Se envía algo a un servidor?
No. El HMAC se calcula en el navegador con WebCrypto.
Próximos pasos
- Hashea el cuerpo por separado primero con el generador de hash si el protocolo pide
body_hashy luego HMAC. - Construye la firma completa de la petición con la herramienta de firma de parámetros.
- Decodifica JWT entrantes con la herramienta codificar/decodificar — los JWT usan HMAC para algoritmos HS-*.