Was ist der Unterschied zwischen HMAC und Hash?

Ein Hash hängt nur vom Inhalt ab, also kann ihn jeder neu berechnen. Ein HMAC hängt vom Inhalt und einem geheimen Schlüssel ab, und nur wer den Schlüssel hat, erzeugt die richtige Signatur. Ein Hash prüft die Integrität, ein HMAC Integrität und Herkunft.

Warum stimmt die Webhook-Signatur nicht?

Meistens wurde der Body vor der Prüfung verändert: JSON.parse gefolgt von JSON.stringify, eine Middleware, die neu formatiert, oder ein zusätzlicher Zeilenumbruch. Danach folgen ein Secret aus der falschen Umgebung, ein Hex- oder Base64-Schlüssel, der als Text verwendet wird, und ein Timestamp aus einer anderen Anfrage. Fügen Sie hier den Roh-Body aus dem Log ein und vergleichen Sie.

Muss ich das sha256= aus der Signatur entfernen?

Hier nicht: Die Seite entfernt Präfixe wie sha256=, sha1= und v0= vor dem Vergleich. Vergleichen Sie in Ihrem Code die ganze Header-Zeichenkette mit "sha256=" + berechnetem Hex, oder entfernen Sie das Präfix vorher, wie es die Dokumentation des Anbieters zeigt.

Kommt die Signatur in Hex oder Base64?

Das hängt vom Anbieter ab. GitHub, Stripe, Mercado Pago und Slack verwenden Hex, Shopify Base64. Beide stellen dieselben Bytes dar, und die Seite erkennt das Format an der Länge: 64 Hex-Zeichen oder 44 Base64-Zeichen bei SHA-256.

Welchen Algorithmus soll ich für HMAC verwenden?

HMAC-SHA256, den die Anbieter nutzen und der De-facto-Standard ist. HMAC-SHA1 ist weiterhin akzeptabel, da die Schwächen von SHA-1 HMAC nicht betreffen, kommt aber vor allem in alten Integrationen vor. Verwenden Sie SHA-512, wenn die Spezifikation es verlangt.

Ist HS256 bei JWT ein HMAC?

Ja. Die Signatur eines HS256-JWT ist der HMAC-SHA256 von header.payload, in base64url geschrieben. Um ein Token zu prüfen, verwenden Sie den JWT-Decoder, der diese Berechnung mit Ihrem Secret durchführt.

Ist das whsec_-Secret von Stripe Base64?

Nicht bei Stripe: Die offizielle Bibliothek verwendet die ganze Zeichenkette whsec_... als Text-Schlüssel. Lassen Sie die Kodierung des Schlüssels auf Text. Andere Dienste nach der Spezifikation Standard Webhooks verwenden ebenfalls whsec_, dekodieren aber das Base64 nach dem Präfix; prüfen Sie daher die jeweilige Dokumentation.

Werden Payload und Schlüssel an einen Server gesendet?

Nein. Der HMAC wird von der Web Crypto API Ihres Browsers berechnet, und nichts, was Sie einfügen, wird gesendet, gespeichert oder in die URL geschrieben. Die Nutzungsstatistik erfasst nur die gewählte Vorlage, den Algorithmus und ob die Signatur übereinstimmte.

HMAC-Generator und Webhook-Prüfer

Berechnen Sie HMAC-SHA256, SHA-384, SHA-512 oder SHA-1 und prüfen Sie, ob die vom Webhook gesendete Signatur übereinstimmt. Die Vorlagen für GitHub, Stripe, Shopify, Mercado Pago und Slack bauen die signierte Nachricht so, wie der jeweilige Anbieter es tut. Payload und Schlüssel bleiben in Ihrem Browser.

Anbieter

HMAC des Payloads unverändert, mit Algorithmus und Kodierung Ihrer Wahl.

Payload (Roh-Body)

Die Signatur deckt den Roh-Body Byte für Byte ab. Ein anderes Leerzeichen, ein Zeilenumbruch oder eine andere Feldreihenfolge ändert das Ergebnis. Fügen Sie den Body genau so ein, wie er ankam, bevor er durch JSON.parse oder einen Formatierer ging.

Geheimer Schlüssel

Der Schlüssel ist

Algorithmus

Signaturformat

Empfangene Signatur (optional)

Signatur

Der Schlüssel fehlt

Geben Sie den geheimen Schlüssel ein. Die Signatur erscheint während der Eingabe.

Ein HS256-JWT ist ein HMAC-SHA256 von Header und Payload. Der Decoder prüft die Signatur des Tokens mit Ihrem Secret.

JWT dekodieren

Möchten Sie den Webhook-Payload lesen? Formatieren Sie ihn in einem anderen Tab. Formatiertes JSON hat andere Bytes und eignet sich nicht zum Prüfen der Signatur.

JSON formatieren

Brauchen Sie nur einen Hash, ohne Schlüssel? Der Hash-Generator berechnet MD5, SHA-1 und SHA-256 für Text und Dateien.

Hash erzeugen

Was ist HMAC

HMAC ist ein Hash, der mit einem geheimen Schlüssel berechnet wird (RFC 2104). Einen einfachen SHA-256 kann jeder nach einer Änderung der Nachricht neu berechnen. Mit HMAC kann nur, wer den Schlüssel kennt, die richtige Signatur erzeugen. Deshalb belegt man damit, dass eine Anfrage vom angegebenen Absender kommt und unterwegs nicht verändert wurde: Webhooks, API-Signaturen wie AWS Signature V4 und HS256-JWTs.

Format der einzelnen Anbieter

Jeder Anbieter legt fest, was er signiert und wie er das Ergebnis schreibt. Die Tabelle fasst die Vorlagen dieser Seite zusammen; jedes Format wurde anhand der offiziellen Dokumentation des Anbieters geprüft.

Anbieter	Header	Was signiert wird	Format
GitHub	X-Hub-Signature-256	Body	sha256=<hex>
Stripe	Stripe-Signature	t.Body	t=<ts>,v1=<hex>
Shopify	X-Shopify-Hmac-Sha256	Body	<base64>
Mercado Pago	x-signature	id:…;request-id:…;ts:…;	ts=<ts>,v1=<hex>
Slack	X-Slack-Signature	v0:timestamp:Body	v0=<hex>

So funktioniert die Webhook-Prüfung

Anbieter und Anwendung teilen dasselbe Secret. Beim Senden des Ereignisses berechnet der Anbieter den HMAC des Bodys oder einer Nachricht aus Timestamp und Body und schickt das Ergebnis in einem Header. Ihre Anwendung berechnet ihn mit dem empfangenen Body neu und vergleicht. Stimmen beide überein, ist das Ereignis echt. Der Vergleich muss in konstanter Zeit laufen, mit crypto.timingSafeEqual in Node, hash_equals in PHP oder hmac.compare_digest in Python, damit die Antwortzeit die Signatur nicht verrät.

Die häufigste Ursache ungültiger Signaturen

Das Framework macht aus dem JSON ein Objekt, bevor Ihr Code läuft, und beim erneuten Serialisieren ändern sich Schlüsselreihenfolge, Leerzeichen und das Escaping von Umlauten. Die Signatur stimmt dann selbst mit dem richtigen Schlüssel nicht mehr. Lesen Sie den Roh-Body: express.raw() in Express, $request->getContent() in Laravel, einen String-Parameter mit @RequestBody in Spring und request.get_data() in Flask. In NestJS erstellen Sie die App mit rawBody: true und verwenden req.rawBody.

Schlüssel als Text, Hex oder Base64

HMAC arbeitet mit den Bytes des Schlüssels. Zeigt das Dashboard des Anbieters ein Secret in Hex und Sie verwenden diese Zeichenkette als Text, sind die Bytes andere und damit auch die Signatur. Die meisten Webhook-Anbieter, darunter GitHub, Stripe, Shopify, Mercado Pago und Slack, verwenden das Secret als Text, so wie es im Dashboard steht, einschließlich des whsec_-Präfixes von Stripe.

Timestamp und Wiederholung

Eine abgefangene gültige Anfrage bleibt gültig, wenn sie erneut gesendet wird. Stripe und Slack nehmen den Timestamp in die signierte Nachricht auf, und ihre Bibliotheken lehnen Ereignisse ab, die älter als 5 Minuten sind. Beim Testen mit einem alten Payload aus dem Log kann die Signatur hier übereinstimmen und trotzdem von Ihrem Server wegen der Uhrzeit abgelehnt werden.

Häufige Fragen zu HMAC

Webhook-Signaturen, Schlüssel, Kodierung und die häufigsten Fehler bei der Prüfung.