La spécification Standard Webhooks face à l'en-tête HMAC de Shopify et au jeton secret partagé de GitLab

Ce que c'est

La spécification Standard Webhooks définit trois en-têtes sur chaque envoi : webhook-id (identifiant unique du message), webhook-timestamp (secondes Unix) et webhook-signature, transmis sous la forme d'une liste de valeurs v1,<base64 signature> séparées par des espaces « pour permettre la rotation du secret sans interruption de service » (des entrées asymétriques v1a, peuvent aussi apparaître). Le contenu signé est msg_id.timestamp.payload, et le secret partagé est « encodé en base64, préfixé par whsec_ pour être facilement identifiable » : la clé HMAC est le reste décodé depuis la base64, et non le texte lui-même. La documentation de GitLab indique que ses jetons de signature (introduits dans la 19.0, disponibles en GA dans GitLab 19.1) suivent cette spécification : « l'envoi des webhooks GitLab suit la spécification Standard Webhooks », et elle demande aux récepteurs de retirer whsec_ puis de décoder le reste depuis la base64. À l'inverse, l'ancien mécanisme de GitLab, le jeton secret, est « envoyé en clair dans l'en-tête HTTP X-Gitlab-Token » : il s'agit d'une comparaison directe de chaînes, pas d'un HMAC, et la documentation de GitLab elle-même le présente désormais comme l'option offrant des « garanties de sécurité plus faibles » et ne le recommande plus pour les nouveaux webhooks. Shopify utilise un troisième schéma, entièrement distinct : un en-tête X-Shopify-Hmac-SHA256 encodé en base64, vérifié en calculant « le HMAC-SHA256 du corps brut de la requête avec le client secret de votre application comme clé » puis en le comparant « à la valeur décodée de l'en-tête ». La signature de Shopify ne comporte aucun horodatage, il n'y a donc pas de fenêtre de protection contre le rejeu ; dédupliquez sur X-Shopify-Webhook-Id.

Pourquoi c'est important

Trois formes de « sécurité des webhooks » sont largement répandues, et une bibliothèque cliente ou un exemple de code écrit pour l'une échouera silencieusement sur une autre : une construction HMAC commune (Standard Webhooks et, désormais, le jeton de signature de GitLab), un HMAC propriétaire à en-tête unique (Shopify), et une comparaison de secret partagé non cryptographique (le jeton historique de GitLab et des schémas similaires).

Comment l'appliquer

• Pour tout fournisseur se déclarant conforme à Standard Webhooks (le jeton de signature de GitLab en fait partie), vérifiez webhook-signature en recalculant le HMAC-SHA256 sur id.timestamp.payload, avec pour clé les octets décodés depuis la base64 de ce qui suit whsec_, puis en encodant le condensé en base64 et en le préfixant par v1, ; acceptez la requête si l'une des entrées séparées par des espaces correspond, au moyen d'une comparaison en temps constant. Vérifiez aussi que webhook-timestamp est récent.
• Pour Shopify, décodez l'en-tête depuis la base64 et comparez les 32 octets obtenus au condensé HMAC-SHA256 brut du corps, jamais à un condensé hexadécimal. Après une rotation du client secret, Shopify peut continuer à signer avec l'ancien secret pendant une heure au plus.
• Pour l'ancien X-Gitlab-Token de GitLab, comparez-le au jeton secret configuré (une comparaison en temps constant reste conseillée) : il n'y a aucune signature à recalculer. Migrez vers le jeton de signature là où il est disponible.
• Ne considérez jamais un simple jeton de secret partagé comme équivalent à un HMAC : le jeton circule dans chaque requête, de sorte que tout élément capable de lire une seule requête (un proxy de journalisation, un intermédiaire qui termine le TLS) peut forger des charges utiles arbitraires, alors qu'un HMAC n'expose jamais la clé et la lie à un corps précis.

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(" "))

Pièges

Appliquer du code de vérification HMAC à un fournisseur qui n'utilise qu'un jeton de secret partagé (il n'y a rien à hacher), ou croire qu'une comparaison en temps constant d'un jeton de secret partagé suffit à combler l'écart avec un HMAC. Ne pas remarquer que GitLab propose désormais les deux mécanismes côte à côte sur le même écran de configuration d'un webhook.