Stripe-Webhook-Signaturen prüfen: Stripe-Signature, Zeitstempel-Toleranz und Secret-Rotation

Worum es geht

Der Webhook-Leitfaden von Stripe dokumentiert den Header Stripe-Signature sowie die Hilfsfunktion constructEvent() zur Prüfung. Sie erwartet den unveränderten Request-Body, den Header-Wert und das Endpoint-Secret (mit dem Präfix whsec_). Der Header enthält einen Zeitstempel t= und eine oder mehrere Signaturen, jeweils mit einem Schema als Präfix; "currently, the only valid live signature scheme is v1". Test-Events enthalten zusätzlich eine Pseudo-Signatur v0, die zu ignorieren ist. Da der Zeitstempel Teil des signierten Payloads ist, wird er durch die Signatur mitgeprüft ("is part of the signed payload, it's also verified by the signature"), und "our libraries have a default tolerance of 5 minutes between the timestamp and the current time." Der signierte String besteht aus dem Zeitstempel, einem . und dem unveränderten Body; als HMAC-Schlüssel dient das Endpoint-Secret genau so, wie es angezeigt wird, also einschliesslich des Präfixes whsec_. Die Troubleshooting-Seite von Stripe zeigt die zugehörige Fehlermeldung: Webhook signature verification failed. Err: No signatures found matching the expected signature for payload.

Warum es wichtig ist

Das Toleranzfenster verhindert, dass ein abgefangener, gültiger Payload erneut eingespielt wird (Replay). Als häufigste Ursache für den obigen Fehler nennt die Troubleshooting-Seite von Stripe ein falsches Endpoint-Secret: Ein Secret aus der CLI (stripe listen) und ein Endpoint-Secret aus dem Dashboard beginnen beide mit whsec_, sind aber verschieden. Am zweithäufigsten ist ein veränderter Body (siehe den Artikel zur Raw-Body-Falle), denn jedes Framework, das das JSON umformatiert, bevor der Handler es erhält, verändert die Bytes, die Stripe signiert hat. Wird ein Secret rotiert und der Ablauf des alten Secrets hinausgezögert (bis zu 24 Stunden), gilt: "Stripe generates one signature per secret until expiration". Der Header enthält dann vorübergehend mehr als einen v1=-Wert, und der Empfänger muss eine Übereinstimmung mit einem beliebigen davon akzeptieren.

So wird es angewendet

• Auf der Webhook-Route den unveränderten, nicht geparsten Body einlesen.
• Stripe-Signature an den Kommas aufteilen, t= als Zeitstempel übernehmen und sämtliche v1=-Werte sammeln.
• Den HMAC-SHA256 von "{t}.{raw_body}" mit dem Endpoint-Secret neu berechnen und mit einer zeitkonstanten Vergleichsfunktion gegen jeden v1-Wert prüfen; bei einer beliebigen Übereinstimmung akzeptieren.
• Ablehnen, wenn der Zeitstempel älter als die Toleranz ist (300 Sekunden, sofern nicht bewusst erweitert). Bei Zeitabweichungen NTP verwenden statt die Toleranz zu erhöhen, und nie 0 übergeben, da dies "disables the recency check entirely", also die Aktualitätsprüfung vollständig abschaltet. Das Snippet lehnt zudem Zeitstempel in der Zukunft ab und ist damit strenger als die Bibliotheken.
• Bei einer verzögerten Rotation das neue whsec_-Secret deployen, bevor das alte abläuft; solange beide aktiv sind, passt jedes von beiden.

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)

Stolpersteine

Ein anwendungsweites express.json() vor der Webhook-Route einbinden; laut der Troubleshooting-Seite von Stripe gehört app.use(express.json()) hinter diese Route. Die Toleranz erhöhen, statt die Zeitabweichung der Uhr zu beheben. Den Header in ein Dictionary parsen: Dabei bleibt nur ein v1-Wert erhalten, sodass gültige Zustellungen während einer Rotation abgelehnt werden. Das Secret Base64-dekodieren, wie es bei Standard Webhooks üblich ist; die Stripe-Bibliotheken verwenden den vollständigen String als Schlüssel.