Standard Webhooks im Vergleich: Shopifys HMAC-Header und GitLabs Shared-Secret-Token

Worum es geht

Die Standard-Webhooks-Spezifikation definiert bei jeder Zustellung drei Header: webhook-id (eine eindeutige Nachrichtenkennung), webhook-timestamp (Unix-Sekunden) und webhook-signature. Der letzte Header enthält eine durch Leerzeichen getrennte Liste von Werten der Form v1,<base64 signature>, "to support zero downtime secret rotation" (also um Secrets ohne Ausfallzeit zu rotieren); daneben können auch asymmetrische Einträge mit v1a, auftreten. Signiert wird der Inhalt msg_id.timestamp.payload. Das gemeinsame Secret ist "base64 encoded, prefixed with whsec_ for easy identification": Als HMAC-Schlüssel dient der Base64-dekodierte Rest, nicht der Text selbst. Laut GitLab-Dokumentation folgen die Signing Tokens (eingeführt in 19.0, allgemein verfügbar in GitLab 19.1) diesem Standard: "GitLab webhook delivery follows the Standard Webhooks specification". Empfänger sollen demnach whsec_ entfernen und den Rest Base64-dekodieren. Der ältere GitLab-Mechanismus, das Secret Token, wird dagegen "sent as plain text in the X-Gitlab-Token HTTP header" und per direktem String-Vergleich geprüft. Es ist also kein HMAC. Die GitLab-Dokumentation selbst bezeichnet diese Option inzwischen als die mit "weaker security guarantees" (schwächeren Sicherheitsgarantien) und empfiehlt sie für neue Webhooks nicht mehr. Shopify verwendet ein drittes, eigenständiges Verfahren: einen Base64-kodierten Header X-Shopify-Hmac-SHA256. Er wird geprüft, indem man den "HMAC-SHA256 of the raw request body using your app's client secret as the key" berechnet und mit dem "decoded header value" (dem dekodierten Header-Wert) vergleicht. Shopifys Signatur enthält keinen Zeitstempel, es gibt also kein Zeitfenster gegen Replay-Angriffe; Duplikate sind über X-Shopify-Webhook-Id zu erkennen.

Warum es wichtig ist

Für "Webhook-Sicherheit" sind drei Varianten weit verbreitet. Eine Client-Bibliothek oder ein Codebeispiel für eine Variante scheitert bei einer anderen unbemerkt. Die drei Varianten sind: eine gemeinsame HMAC-Konstruktion (Standard Webhooks und inzwischen GitLabs Signing Token), ein proprietärer HMAC in einem einzelnen Header (Shopify) und ein nicht kryptografischer Vergleich eines Shared Secrets (GitLabs älteres Token und ähnliche Verfahren).

So wird es angewendet

• Bei jedem Anbieter, der Standard-Webhooks-Konformität beansprucht (GitLabs Signing Token gehört dazu), webhook-signature wie folgt prüfen: HMAC-SHA256 über id.timestamp.payload neu berechnen, mit den Base64-dekodierten Bytes nach whsec_ als Schlüssel, den Digest Base64-kodieren, v1, voranstellen und akzeptieren, wenn ein beliebiger durch Leerzeichen getrennter Eintrag im Constant-Time-Vergleich übereinstimmt. Zusätzlich prüfen, ob webhook-timestamp aktuell ist.
• Bei Shopify den Header Base64-dekodieren und die resultierenden 32 Bytes mit dem rohen HMAC-SHA256-Digest des Bodys vergleichen, niemals mit einem Hex-Digest. Nach einer Rotation des Client Secrets signiert Shopify unter Umständen bis zu eine Stunde lang weiter mit dem alten Secret.
• Beim älteren GitLab-Header X-Gitlab-Token den Wert mit dem konfigurierten Secret Token vergleichen (ein Constant-Time-Vergleich ist weiterhin ratsam). Es gibt keine Signatur, die neu zu berechnen wäre. Wo verfügbar, auf das Signing Token migrieren.
• Ein schlichtes Shared-Secret-Token nie als gleichwertig mit einem HMAC behandeln: Das Token wird mit jeder Anfrage übertragen. Wer eine einzige Anfrage mitlesen kann (etwa ein Logging-Proxy oder eine TLS-terminierende Zwischenstelle), kann daher beliebige Payloads fälschen. Ein HMAC dagegen legt den Schlüssel nie offen und bindet die Signatur an genau einen Body.

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

Stolpersteine

HMAC-Prüfcode auf einen Anbieter anzuwenden, der nur ein Shared-Secret-Token nutzt (es gibt nichts zu hashen), oder anzunehmen, ein Shared-Secret-Token lasse sich per Constant-Time-Vergleich absichern, als schlösse das die Lücke zu einem HMAC. Ausserdem wird leicht übersehen, dass GitLab inzwischen beide Mechanismen nebeneinander auf demselben Konfigurationsbildschirm eines Webhooks anbietet.