Un Código de Autenticación de Mensajes Basado en Hash con Clave (HMAC) demuestra tanto la integridad de los datos (el payload no fue alterado en tránsito) como la autenticidad (el remitente posee la clave secreta compartida). Reproducir la firma de un proveedor requiere hacer coincidir tres parámetros exactos: la primitiva hash subyacente, la decodificación en bytes puros de la clave secreta y la secuencia exacta de bytes del payload firmado.
Ejemplo 1: Caso de Prueba 2 de IETF RFC 2104 / RFC 2202 / RFC 4231
Ya sea que introduzcas la clave secreta de 4 bytes como texto UTF-8 Jefe, hexadecimal puro 4a656665 o Base64 SmVmZQ==, se decodifica al mismo búfer de clave [0x4a, 0x65, 0x66, 0x65]. Firmar el mensaje UTF-8 de 28 bytes what do ya want for nothing? produce:
{
"keyUtf8": "Jefe",
"keyHex": "4a656665",
"keyBase64": "SmVmZQ==",
"message": "what do ya want for nothing?",
"signatures": {
"hmac_md5_hex": "750c783e6ab0b503eaa86e310a5db738",
"hmac_sha1_hex": "effcdf6ae5eb2fa2d27416d5f184df9c259a7c79",
"hmac_sha256_hex": "5bdcc146bf60754e6a042426089575c75a003f089d2739839dec58b964ec3843",
"hmac_sha256_base64": "W9zBRr9gdU5qBCQmCJV1x1oAPwidJzmDnexYuWTsOEM=",
"hmac_sha256_base64url": "W9zBRr9gdU5qBCQmCJV1x1oAPwidJzmDnexYuWTsOEM",
"hmac_sha384_hex": "af45d2e376484031617f78d2b58a6b1b9c7ef464f5a01b47e42ec3736322445e8e2240ca5e69e2c78b3239ecfab21649",
"hmac_sha512_hex": "164b7a7bfcf819e2e395fbe73b56e0a387bd64222e831fd610270cd7ea2505549758bf75c05a994a6d034f65f8f0e6fdcaeab1a34d4a6b4b636e070a38bce737"
}
}
Ejemplo 2: Base64 vs Base64URL y Payloads Canónicos de Webhooks
El formato Base64 estándar (RFC 4648 Sección 4) emite +, / y relleno final =, mientras que Base64URL seguro para URL (RFC 4648 Sección 5, utilizado en firmas JWS/JWT y URLs firmadas) sustituye + por -, / por _ y elimina el relleno =. Firmar The quick brown fox jumps over the lazy dog con la clave UTF-8 key bajo HMAC-SHA256 ilustra directamente la diferencia de codificación:
Key (UTF-8): key
Message (UTF-8): The quick brown fox jumps over the lazy dog
HMAC-SHA256 Hex: f7bc83f430538424b13298e6aa6fb143ef4d59a14946175997479dbc2d1a3cd8
HMAC-SHA256 Base64: 97yD9DBThCSxMpjmqm+xQ+9NWaFJRhdZl0edvC0aPNg=
HMAC-SHA256 Base64URL: 97yD9DBThCSxMpjmqm-xQ-9NWaFJRhdZl0edvC0aPNg
Al verificar cabeceras de webhooks reales, construye el payload exacto previo a la firma definido por cada proveedor antes de eliminar los prefijos de la cabecera:
GitHub (X-Hub-Signature-256: sha256=<hex>):
Signed input = <raw_http_body>
Stripe (Stripe-Signature: t=1730419200,v1=<hex>):
Signed input = 1730419200.<raw_http_body>
Slack (X-Slack-Signature: v0=<hex>):
Signed input = v0:1730419200:<raw_http_body>
Shopify (X-Shopify-Hmac-Sha256: <base64>):
Signed input = <raw_http_body>