La especificación Standard Webhooks frente a la cabecera HMAC de Shopify y al token de secreto compartido de GitLab

Qué es

La especificación Standard Webhooks define tres cabeceras en cada entrega: webhook-id (un identificador único del mensaje), webhook-timestamp (segundos Unix) y webhook-signature, que se envía como una lista separada por espacios de valores v1,<base64 signature> "para permitir la rotación de secretos sin tiempo de inactividad" (también pueden aparecer entradas asimétricas v1a,). El contenido firmado es msg_id.timestamp.payload, y el secreto compartido está "codificado en base64, con el prefijo whsec_ para facilitar su identificación": la clave HMAC es el resto decodificado desde base64, no el texto tal cual. La documentación de GitLab afirma que sus tokens de firma (introducidos en la versión 19.0 y con disponibilidad general en GitLab 19.1) siguen esta especificación: "La entrega de webhooks de GitLab sigue la especificación Standard Webhooks", e indica a los receptores que quiten whsec_ y decodifiquen el resto desde base64. En cambio, el mecanismo anterior de GitLab, el token secreto, "se envía como texto plano en la cabecera HTTP X-Gitlab-Token": es una comparación directa de cadenas, no un HMAC, y la propia documentación de GitLab lo describe ahora como la opción con "garantías de seguridad más débiles" y ya no lo recomienda para webhooks nuevos. Shopify usa un tercer esquema completamente distinto: una cabecera X-Shopify-Hmac-SHA256 codificada en base64, que se verifica calculando el "HMAC-SHA256 del cuerpo sin procesar de la petición usando el client secret de tu app como clave" y comparándolo "con el valor decodificado de la cabecera". La firma de Shopify no incluye marca de tiempo, por lo que no existe ventana de protección contra repetición; hay que deduplicar con X-Shopify-Webhook-Id.

Por qué importa

Se usan ampliamente tres formas de "seguridad de webhooks", y una biblioteca cliente o un ejemplo de código pensado para una fallará sin avisar con otra: una construcción HMAC compartida (Standard Webhooks y, ahora, el token de firma de GitLab), un HMAC propietario en una sola cabecera (Shopify) y una comparación de secreto compartido sin criptografía (el token heredado de GitLab y esquemas similares).

Cómo aplicarlo

• Con cualquier proveedor que declare cumplir Standard Webhooks (el token de firma de GitLab es uno de ellos), verifica webhook-signature recalculando HMAC-SHA256 sobre id.timestamp.payload, con los bytes decodificados desde base64 que siguen a whsec_ como clave; codifica el resumen en base64, anteponle v1, y acepta la firma si alguna de las entradas separadas por espacios coincide en una comparación en tiempo constante. Comprueba además que webhook-timestamp sea reciente.
• Con Shopify, decodifica la cabecera desde base64 y compara los 32 bytes resultantes con el resumen HMAC-SHA256 en bruto del cuerpo; nunca con un resumen en hexadecimal. Tras rotar el client secret, Shopify puede seguir firmando con el secreto anterior hasta una hora.
• Con el X-Gitlab-Token heredado de GitLab, compáralo con el token secreto configurado (sigue siendo aconsejable una comparación en tiempo constante); no hay ninguna firma que recalcular. Migra al token de firma donde esté disponible.
• Nunca trates un token de secreto compartido como equivalente a un HMAC: el token viaja en cada petición, de modo que cualquier elemento que pueda leer una sola (un proxy que registre tráfico, un intermediario que termine TLS) puede falsificar cargas arbitrarias, mientras que un HMAC nunca expone la clave y la vincula a un cuerpo exacto.

import base64, hashlib, hmac

def verify_standard(secret: str, msg_id: str, ts: str, raw_body: bytes, header: str) -> bool:
    key = base64.b64decode(secret.removeprefix("whsec_"))
    signed = msg_id.encode() + b"." + ts.encode() + b"." + raw_body
    expected = b"v1," + base64.b64encode(hmac.new(key, signed, hashlib.sha256).digest())
    return any(hmac.compare_digest(expected, s.encode()) for s in header.split(" "))

Trampas

Aplicar código de verificación HMAC a un proveedor que solo usa un token de secreto compartido (no hay nada que calcular), o suponer que una comparación en tiempo constante de un token de secreto compartido cierra la brecha con un HMAC. Pasar por alto que GitLab ofrece ahora ambos mecanismos, uno junto al otro, en la misma pantalla de configuración del webhook.