HMAC-Webhook-Signatur prüfen: so geht es richtig
Jeder, der die URL Ihres Webhook-Endpunkts kennt – oder errät –, kann einen JSON-Body per POST senden, der genau wie ein echtes Ereignis aussieht: gleiche Struktur, gleiche Feldnamen, komplett gefälscht. Die Signatur schließt diese Lücke: Beweis, dass eine Nutzlast von der Inhaberin des gemeinsamen Geheimnisses stammt und dass sich während der Übertragung nichts daran verändert hat. Stripe, GitHub und die meisten seriösen Anbieter signieren mit einer Variante desselben HMAC-Schemas, sodass die Mechanik hier fast universell ist – das konkrete Beispiel ist Olmiras eigenes, echtes, aktuelles Schema, inklusive Header-Namen.
Was HMAC tatsächlich beweist
HMAC (Hash-based Message Authentication Code) geht von einem Geheimnis aus, das beide Seiten kennen und sonst niemand. Der Absender hasht die Nutzlast zusammen mit diesem Geheimnis und hängt das Ergebnis an; Sie, im Besitz desselben Geheimnisses, berechnen es neu und vergleichen. Eine Übereinstimmung beweist zwei Dinge gleichzeitig: Die Nachricht kam wirklich von jemandem, der das Geheimnis besitzt – keine noch so genaue Kenntnis der Nutzlast lässt einen Angreifer den Hash fälschen – und sie wurde nach dem Signieren nicht verändert, weil schon die Änderung eines einzigen Zeichens einen völlig anderen Hash erzeugt.
Das genaue Schema, das Olmira verwendet
Jede ausgehende Webhook-Zustellung trägt drei Header:
X-Aether-Signature, X-Aether-Webhook-Id und X-Aether-Event. (Das Header-Präfix lautet Aether statt Olmira – ein Überbleibsel des internen Codenamens der Plattform; das ändert nichts an der Funktionsweise des Verfahrens, nur daran, wie der Header wörtlich heißt.)Eine Zustellung verifizieren, ganz einfach erklärt
Nehmen Sie den rohen Anfragetext – die exakten Bytes, wie geliefert, vor jeglichem JSON-Parsing –, stellen Sie ihm den Zeitstempel aus dem Signatur-Header und einen Punkt voran, berechnen Sie den HMAC dieser Zeichenkette mit dem Geheimnis Ihres Endpunkts, und vergleichen Sie das Ergebnis mit der gelieferten Signatur mittels eines zeitkonstanten Vergleichs. Node's eingebautes
crypto-Modul deckt das alles ohne eine einzige Abhängigkeit ab; die Vorabprüfungen unten sind die Stelle, an der sich korrekte Implementierungen tatsächlich von fehlerhaften unterscheiden.Die Fehler, an denen die Verifizierung scheitert
Fast jede Meldung „meine Signatur stimmt nie überein“ geht auf eine von wenigen Ursachen zurück. Einen neu geparsten oder neu serialisierten Body zu hashen statt der exakten Rohbytes ist mit großem Abstand die häufigste — Leerzeichen, Schlüsselreihenfolge oder Zahlenformatierung können sich alle unbemerkt ändern, wenn ein Body durch einen JSON-Parser und wieder zurück in eine Zeichenkette läuft, und jede noch so kleine Änderung erzeugt einen anderen Hash. Zu vergessen, dass der Zeitstempel Teil des Signierten ist — also nur den Body zu hashen, ohne das Präfix
. — ist die zweithäufigste, und sie passiert leicht, weil der Body das „naheliegendere“ zu Hashende ist.Bevor Sie ihm im Produktivbetrieb vertrauen
1
Prüfen Sie zuerst das Zeitstempel-Fenster
Weisen Sie alles ab, was außerhalb einer kleinen Toleranz liegt (Olmira nennt 300 Sekunden, also fünf Minuten, als eigenen Referenzwert), bevor Sie CPU-Zeit fürs Hashen aufwenden — eine veraltete Signatur verdient den Vergleich nicht.
2
In konstanter Zeit vergleichen
Verwenden Sie die Vergleichsprimitive Ihrer Sprache mit konstanter Laufzeit statt eines einfachen Gleichheitsvergleichs, damit eine Abweichung nie über die Laufzeit verrät, wie nah ein Versuch war.
3
Stellen Sie sicher, dass Sie den rohen Request-Body hashen
Protokollieren Sie während der Einrichtung mindestens einmal genau die Zeichenkette, die Ihr Code hashen will, und vergleichen Sie sie Byte für Byte mit dem, was eine Testzustellung tatsächlich gesendet hat.
4
Planen Sie den Wechsel des Secrets ein
Wo auch immer Sie das Secret speichern: Machen Sie daraus eine einzeilige Konfigurationsänderung — wer es im Dashboard rotiert, ohne es im selben Moment zu aktualisieren, sorgt dafür, dass jede Zustellung fehlschlägt, bis er nachzieht.
Wie Olmira das löst
Jedes der 22 Webhook-Ereignisse von Olmira — Bestellungen, Buchungen, Zahlungen, Rechnungen, Support-Tickets und weitere — wird exakt auf die oben beschriebene Weise signiert, ohne Ausnahmen und ohne unsignierte Ereignistypen. Jeder Endpoint, den Sie registrieren, erhält sein eigenes unabhängiges Secret, sodass ein Leck bei einer Integration nie eine andere kompromittiert. Bevor Sie live gehen, löst die Aktion „Test senden“ in den Einstellungen des Endpoints eine echte, vollständig signierte Beispielzustellung über genau denselben Code-Pfad wie ein Live-Ereignis aus — mit denselben Headern und derselben Envelope-Struktur — sodass Sie Ihren Verifier gegen das reale Verfahren prüfen können, ohne auf eine echte Bestellung oder Buchung warten zu müssen. Die vollständige Connector-Plattform, in der das steckt — CSV-Import, geplante Abrufe und eingehende Pushes neben ausgehenden Webhooks — ist Integrationen.
Weiterführende Artikel
Datenfehler beim CSV-Import — und die Lösung — dieselbe Disziplin „explizit verifizieren, nicht stillschweigend vertrauen“, angewendet auf die Daten, die in die andere Richtung fließen.
Ihr Unternehmen von Tabellenkalkulationen befreien: eine praktische Übersicht — woher importierte Daten überhaupt meistens stammen.
Quell-IPs verschieben sich — hinter Load Balancern, durch Infrastrukturänderungen des Anbieters, im Lauf der Zeit — und sie auf eine Positivliste zu setzen ist in der Praxis brüchig. Eine kryptografische Signatur belegt die Echtheit unabhängig vom Netzwerkpfad, und das ist eine stärkere und stabilere Garantie als „die Anfrage kam aus einem Bereich, den wir heute erkannt haben“.
Nein — das Verfahren ist überall identisch. Pro Endpunkt unterscheidet sich nur das Secret selbst, da jedes unabhängig erzeugt wird.
Nein — prüfen Sie die Signatur, bestätigen Sie schnell und erledigen Sie alles Langsame (Datenbankschreibvorgänge, Aufrufe anderer Systeme) danach asynchron. Ein Webhook-Absender, bei dem das Warten auf Ihren Endpunkt in eine Zeitüberschreitung läuft, wertet das in der Regel als Fehlschlag und versucht es erneut — und das wollen Sie nicht auslösen, weil Sie langsam waren statt tatsächlich gescheitert.
Weisen Sie die Anfrage ab, bevor Sie irgendetwas anderes verarbeiten – eine 4xx-Antwort und sonst nichts. Beschreiben Sie im Antwortkörper nicht, warum sie fehlgeschlagen ist; wer Ihren Endpunkt abklopft, sollte keine kostenlose Rückmeldung darüber bekommen, welcher Teil einer gefälschten Signatur falsch war.