Webhook-HMAC-Signaturprüfung
Stimmt eine Webhook-Signatur nicht, fügen Sie Body und Geheimnis ein, um den Grund zu finden: Der HMAC wird in Ihrem Browser berechnet und mit der empfangenen Signatur verglichen. Body und Geheimnis werden an keinen Server gesendet; die Berechnung nutzt die eigenen Kryptografiefunktionen des Browsers.
Der signierte Text muss Byte für Byte dem entsprechen, was der Empfänger erhalten hat. Zeilenenden, Leerraum und ein abschließender Zeilenumbruch verändern das Ergebnis. Body: 0 Byte (UTF-8)
Der vom Anbieter vergebene Schlüssel. Präfixe wie whsec_ gehören oft zum Schlüssel, oder der Teil nach dem Präfix ist Base64; schauen Sie in die Dokumentation des Anbieters.
Fügen Sie den Header-Wert unverändert ein; Präfixe wie sha256=, v1= und die Form t=…,v1=… werden entfernt. Hex und Base64/Base64url werden akzeptiert.
Geheimnis und Body verlassen Ihr Gerät nicht; die Berechnung läuft im Browser, nichts wird gespeichert. Verwenden Sie dennoch ein Testgeheimnis, statt Produktionsgeheimnisse in eine Webseite einzufügen.
Beim Prüfen beachten
- Prüfen Sie die Signatur immer über die empfangenen Rohbytes. Wandelt Ihr Framework den Body in JSON und wieder in Text um, können sich Schlüsselreihenfolge, Leerraum und Escaping ändern; erfassen Sie den Rohbody vor diesem Schritt.
- Vergleichen Sie Signaturen auf dem Server mit einer zeitkonstanten Funktion, nicht mit ==: crypto.timingSafeEqual in Node, hmac.compare_digest in Python. Ein Vergleich, der früh abbricht, kann die Signatur über Zeitunterschiede preisgeben. Auch diese Seite vergleicht zeitkonstant, ein Ergebnis im Browser ist jedoch keine Sicherheitsgrenze.
- Eine Signatur allein verhindert keine Replay-Angriffe. Sendet der Anbieter einen Zeitstempel, nehmen Sie ihn in die Signatur auf und lehnen Sie Anfragen außerhalb eines Toleranzfensters (z. B. 5 Minuten) ab; speichern Sie Ereignis-IDs und ignorieren Sie Wiederholungen.
- Bewahren Sie das Geheimnis nicht im Code oder in Logs auf; nutzen Sie eine Umgebungsvariable oder ein Secrets-Management und erneuern Sie es sofort bei Verdacht auf ein Leck.
Dieses Werkzeug zeigt nur die Signaturberechnung und den Vergleich; es prüft nicht die Details des Signaturschemas Ihres Anbieters (Zeitstempelverkettung, Schlüsselpräfix, Header-Name). Fügen Sie keine Produktionsgeheimnisse in eine Webseite ein; verwenden Sie ein Testgeheimnis.
Möchten Sie Ihre Webhook-Empfänger sicher, Replay-fest und nachvollziehbar aufbauen? Wir können Signaturprüfung, Retries und Warteschlangen gemeinsam entwerfen.
Gespräch anfragen01
So funktioniert es
A
Fügen Sie den rohen Webhook-Body und das Geheimnis ein; wählen Sie Schlüsselformat (Text, Hex, Base64) und Algorithmus.
B
Sehen Sie die berechnete Signatur als Hex und Base64; fügen Sie die Signatur aus dem Header ein, wird die Übereinstimmung sofort angezeigt.
C
Stimmt sie nicht überein, gehen Sie die Liste der Ursachen durch: Unterschiede in den Rohbytes, Schlüsselformat und Algorithmus sind am häufigsten.
02
Wie eine Webhook-Signatur funktioniert
Der Absender berechnet aus dem Request-Body und einem mit dem Empfänger geteilten Geheimnis einen HMAC und sendet ihn in einem Header (z. B. X-Hub-Signature-256: sha256=…). Der Empfänger führt dieselbe Berechnung mit seiner Kopie des Geheimnisses durch; sind die Ergebnisse gleich, stammt die Anfrage von einer Partei, die das Geheimnis kennt, und der Body wurde unterwegs nicht verändert.
HMAC verbindet eine Hashfunktion (SHA-256, SHA-384, SHA-512) mit einem Schlüssel; es liefert Authentizität und Integrität, keine Vertraulichkeit. Der Body wird nicht verschlüsselt, nur signiert.
03
Berechnung und Prüfung
Das Werkzeug wandelt Schlüssel und Body in Bytes um (Text als UTF-8) und berechnet den HMAC mit der WebCrypto-Funktion crypto.subtle des Browsers. Das Ergebnis wird als Hex (Kleinbuchstaben) und als Base64 angezeigt. Die Berechnung wurde mit den Testvektoren aus RFC 4231 geprüft.
Die empfangene Signatur kann Hex oder Base64/Base64url sein; gewählt wird die Form, deren Länge zur Ausgabe des Algorithmus passt. Der Vergleich läuft über alle Bytes, ohne beim ersten Unterschied abzubrechen.
04
Unterschiede zwischen Anbietern
GitHub sendet die Signatur als sha256=<hex> und signiert den rohen Body. Stripe sendet t=<Zeit>,v1=<hex> und signiert Zeitstempel und Body als „t.body“ verbunden; legen Sie in diesem Fall den verbundenen Text in das Body-Feld. Manche Anbieter senden die Signatur als Base64, manche verlangen den Schlüssel Base64-kodiert.
Im Zweifel geben Sie die Beispielanfrage und die erwartete Signatur aus der Dokumentation des Anbieters ein und bestätigen, dass die Berechnung übereinstimmt; übertragen Sie dieselben Schritte dann in Ihren Code.
Häufige Fragen
- Wird mein Geheimnis irgendwohin gesendet?
- Nein. Die Berechnung läuft auf Ihrem Gerät mit der eingebauten WebCrypto-Funktion des Browsers; weder Schlüssel noch Body werden an einen Server gesendet oder gespeichert. Verwenden Sie trotzdem ein Testgeheimnis, statt Geheimnisse aus Live-Systemen einzufügen.
- Warum stimmt die Signatur nicht, obwohl ich den Body genau eingefügt habe?
- Das Textfeld wandelt Zeilenenden in LF um und kann unsichtbare Zeichen verbergen. Hat der Anbieter den Body mit CRLF signiert, wählen Sie bei der Option Zeilenende CRLF. Auch ein abschließender Zeilenumbruch und der Leerraum im JSON müssen übereinstimmen. Am zuverlässigsten ist es, den Rohbody auf Ihrem Server zu loggen und von dort zu kopieren.
- Was tun, wenn der Schlüssel Base64 ist?
- Wählen Sie Base64 als Schlüsselformat; das Werkzeug dekodiert den Schlüssel zuerst in Bytes. Bei manchen Anbietern wie Stripe ist der Teil nach dem Präfix whsec_ der Base64-kodierte Schlüssel: Entfernen Sie das Präfix und geben Sie den Rest als Base64 ein. Den ganzen Text samt Präfix als Schlüssel zu nehmen, ergibt ein falsches Ergebnis.
- Warum ein zeitkonstanter Vergleich statt ==?
- == oder === bricht beim ersten abweichenden Byte ab; so kann ein Angreifer die Signaturbytes aus Antwortzeiten erraten. Ein zeitkonstanter Vergleich verwendet für alle Bytes dieselbe Zeit. Nutzen Sie auf dem Server crypto.timingSafeEqual (Node) oder hmac.compare_digest (Python); beide Eingaben müssen gleich lang sein.
- Was soll ich statt HMAC-SHA256 wählen?
- Das, was in der Dokumentation Ihres Anbieters steht. In der Praxis nutzen fast alle Webhooks SHA-256; SHA-384 und SHA-512 liefern längere Ausgaben und kommen bei manchen Anbietern vor. Entwerfen Sie ein neues System, genügt HMAC-SHA256. Ältere SHA-1-basierte Signaturen bietet dieses Werkzeug nicht.
Bauen wir Ihre Webhook-Integrationen sicher auf
Wir entwerfen Webhook-Empfänger zwischen CRM-, ERP-, Zahlungs- und Logistiksystemen mit Signaturprüfung, Replay-Schutz und Retries. Besprechen wir Ihren bestehenden Ablauf in einem kostenlosen Erstgespräch.