Vérifier les signatures des webhooks Stripe : Stripe-Signature, tolérance sur l'horodatage et rotation du secret

Ce que c'est

Le guide des webhooks de Stripe documente l'en-tête Stripe-Signature ainsi que la fonction de vérification constructEvent(), qui prend en entrée le corps brut de la requête, la valeur de l'en-tête et le secret de l'endpoint (préfixé par whsec_). L'en-tête contient un horodatage t= et une ou plusieurs signatures, chacune précédée d'un identifiant de schéma. Selon la documentation, "currently, the only valid live signature scheme is v1" ; les événements de test comportent en outre une fausse signature v0, qu'il faut ignorer. L'horodatage "is part of the signed payload, it's also verified by the signature" (il fait partie des données signées et est donc lui aussi vérifié par la signature), et Stripe précise : "our libraries have a default tolerance of 5 minutes between the timestamp and the current time." La chaîne signée se compose de l'horodatage, d'un . et du corps brut ; la clé HMAC est le secret de l'endpoint tel qu'il est affiché, préfixe whsec_ compris. La page de dépannage de Stripe indique le message d'erreur correspondant : Webhook signature verification failed. Err: No signatures found matching the expected signature for payload.

Pourquoi c'est important

La fenêtre de tolérance empêche le rejeu d'un payload valide intercepté. D'après la page de dépannage de Stripe, la cause la plus fréquente de l'erreur ci-dessus est un mauvais secret d'endpoint (le secret fourni par la CLI stripe listen et celui d'un endpoint du Dashboard commencent tous deux par whsec_ mais sont différents) ; vient ensuite un corps modifié (voir l'article sur le piège du corps brut), car tout framework qui reformate le JSON avant qu'il n'atteigne votre handler modifie les octets signés par Stripe. Lorsque vous effectuez la rotation d'un secret en retardant l'expiration de l'ancien (jusqu'à 24 heures), "Stripe generates one signature per secret until expiration" : l'en-tête contient alors temporairement plusieurs valeurs v1=, et le récepteur doit accepter une correspondance avec n'importe laquelle d'entre elles.

Comment l'appliquer

• Lire le corps brut, non parsé, sur la route du webhook.
• Découper Stripe-Signature sur les virgules, lire t= comme horodatage et collecter toutes les valeurs v1=.
• Recalculer le HMAC-SHA256 de "{t}.{raw_body}" avec le secret de l'endpoint et le comparer à chaque valeur v1 au moyen d'une fonction à temps constant ; accepter dès qu'une valeur correspond.
• Rejeter la requête si l'horodatage dépasse la tolérance (300 secondes, sauf élargissement délibéré) ; synchroniser l'horloge via NTP plutôt que d'augmenter la tolérance, et ne jamais passer 0, valeur qui "disables the recency check entirely" (désactive entièrement le contrôle de fraîcheur). L'extrait ci-dessous rejette aussi les horodatages situés dans le futur, ce qui est plus strict que les bibliothèques.
• Lors d'une rotation avec expiration différée, déployer le nouveau secret whsec_ avant l'expiration de l'ancien ; tant que les deux sont actifs, l'un comme l'autre produit une correspondance.

import hmac, hashlib, time

def verify_stripe(secret: str, raw_body: bytes, header: str, tolerance: int = 300) -> bool:
    ts, sigs = None, []
    for item in header.split(","):
        key, _, value = item.strip().partition("=")
        if key == "t" and value.isdecimal():
            ts = value
        elif key == "v1":                        # ignore v0 and unknown schemes
            sigs.append(value.encode())
    if ts is None or not sigs or abs(time.time() - int(ts)) > tolerance:
        return False
    signed = ts.encode() + b"." + raw_body       # exact bytes Stripe signed
    expected = hmac.new(secret.encode(), signed, hashlib.sha256).hexdigest().encode()
    return any(hmac.compare_digest(expected, s) for s in sigs)

Pièges

Monter un express.json() global à l'application avant la route du webhook ; la page de dépannage de Stripe recommande de placer app.use(express.json()) après celle-ci. Augmenter la tolérance au lieu de corriger le décalage d'horloge. Parser l'en-tête dans un dictionnaire, qui ne conserve qu'une seule valeur v1 et fait donc rejeter des livraisons valides pendant une rotation. Décoder le secret en Base64 comme le fait Standard Webhooks ; les bibliothèques Stripe utilisent la chaîne complète comme clé.