Thema: webhooks
-
Standard Webhooks im Vergleich: Shopifys HMAC-Header und GitLabs Shared-Secret-Token
Die Standard-Webhooks-Spezifikation definiert die Header webhook-id, webhook-timestamp und webhook-signature, ein mit whsec_ präfixiertes Base64-Secret, dessen dekodierte Bytes den HMAC-Schlüssel bilden, sowie eine Signatur v1,<base64> über "{id}.{timestamp}.{payload}". GitLabs Signing Tokens (GitLab 19.0, allgemein verfügbar ab 19.1) setzen genau das um. Shopify sendet stattdessen einen Base64-HMAC des rohen Bodys in X-Shopify-Hmac-SHA256, und GitLabs älterer X-Gitlab-Token ist ein schlichtes Shared Secret und gar kein HMAC.
-
Slack-Request-Signaturen prüfen: X-Slack-Signature, 5-Minuten-Replay-Fenster und die 3-Sekunden-Regel
Slack signiert Requests als v0=<Hex-HMAC-SHA256> des Strings "v0:{timestamp}:{raw body}" im Header X-Slack-Signature, zusammen mit X-Slack-Request-Timestamp. Slacks eigenes Beispiel weist Requests ab, deren Zeitstempel mehr als fünf Minuten von der lokalen Zeit abweicht. Slash Commands und interaktive Payloads müssen zusätzlich innerhalb von drei Sekunden bestätigt werden, bevor aufwendige Verarbeitung beginnt.
-
Stripe-Webhook-Signaturen prüfen: Stripe-Signature, Zeitstempel-Toleranz und Secret-Rotation
Stripe sendet einen Stripe-Signature-Header der Form t=<timestamp>,v1=<hex signature>. Die Signatur ist ein HMAC-SHA256 über den String "{timestamp}.{raw body}", als Schlüssel dient das vollständige whsec_-Endpoint-Secret. Die Stripe-Bibliotheken lehnen standardmässig Signaturen ab, deren Zeitstempel mehr als fünf Minuten (300 Sekunden) alt ist, und solange ein rotiertes Secret noch gültig bleibt (bis zu 24 Stunden), enthält der Header pro aktivem Secret einen eigenen v1-Wert.
-
Idempotente Webhook-Verarbeitung: Delivery-IDs, Retry-Zeitpläne der Anbieter und schnelle Antworten
Alle grossen Webhook-Anbieter können dasselbe Event mehrfach zustellen und erwarten, dass der Empfänger mithilfe einer anbieterspezifischen Kennung dedupliziert: X-GitHub-Delivery, die Stripe-Event-ID, die event_id von Slack mit X-Slack-Retry-Num oder die webhook-id von Standard Webhooks. Die Retry-Zeitpläne unterscheiden sich stark: GitHub wiederholt nie automatisch (manuelle oder API-Neuzustellung behält die Delivery-ID), Stripe wiederholt im Live-Modus bis zu drei Tage, Slack dreimal innerhalb von etwa sechs Minuten.
-
GitHub-Webhook-Signaturen prüfen: X-Hub-Signature-256, zeitkonstanter Vergleich und Delivery-IDs
GitHub signiert jede Webhook-Auslieferung mit HMAC-SHA256 über den rohen Request-Body und sendet das Ergebnis als sha256=<Hex-Digest> im Header X-Hub-Signature-256. Der Empfänger muss den Digest aus den exakt empfangenen Bytes neu berechnen, mit einer zeitkonstanten Funktion vergleichen und über X-GitHub-Delivery erneut zugestellte Events erkennen; der ältere Header X-Hub-Signature (HMAC-SHA1) bleibt nur aus Kompatibilitätsgründen erhalten.
-
Die Raw-Body-Falle: Warum JSON-Body-Parser die Prüfung von Webhook-Signaturen scheitern lassen
HMAC-basierte Webhook-Signaturen werden über die exakten Bytes berechnet, die der Anbieter gesendet hat. Jede JSON-Middleware, die den Body vor dem Handler parst, umsortiert oder neu serialisiert, verändert diese Bytes und macht die Signatur ungültig. Express, FastAPI, Flask, Django und Go benötigen jeweils einen eigenen Weg, den unveränderten Body vor dem normalen Parsing oder an dessen Stelle zu erfassen.
Maschinenlesbar: JSON