Wie Webhook-Signaturen funktionieren
Ein Webhook ist nur ein HTTP-POST vom Server eines anderen, und jeder kann an Ihre URL posten. Um zu beweisen, dass die Anfrage vom Anbieter kam, berechnet er einen HMAC über den Body mit einem Secret, das nur Sie beide kennen, und sendet ihn in einem Header. Sie rechnen nach und vergleichen. Das Secret reist nie; nur der Hash.
Warum „invalid signature“ passiert
- Sie haben den geparsten Body gehasht, nicht die rohen Bytes. Frameworks, die JSON parsen, bevor Ihr Handler läuft (Express mit
express.json(), Rails, Django), geben Ihnen ein Objekt; es neu zu serialisieren ändert Leerraum und Schlüsselreihenfolge, und der Hash passt nicht mehr. Erfassen Sie den rohen Body. - Falsches Secret. Stripe hat pro Endpunkt und pro Umgebung ein anderes
whsec_; GitHubs Secret ist pro Webhook; Slacks Signing Secret ist nicht das Bot-Token. - Der Anbieter signiert mehr als den Body. Stripe signiert
timestamp.body; Slack signiertv0:timestamp:body; Svix signiertid.timestamp.body; Twilio signiert die URL plus sortierte Formularfelder. Das Rezept für jeden wird oben angezeigt, wenn Sie ihn wählen. - Kodierung. Manche Anbieter senden Hex, manche Base64; manche stellen
sha256=voran. Vergleichen Sie die Formen. - Proxys. Ein Proxy oder CDN, der den Body neu kodiert (gzip, Zeichensatz), oder ein Größenlimit, das ihn abschneidet, bricht den Hash.
Sicher vergleichen
In Produktion vergleichen Sie mit einer Funktion konstanter Laufzeit (crypto.timingSafeEqual, hmac.compare_digest, hash_equals) und prüfen, dass der Zeitstempel aktuell ist (Stripe und Slack erlauben fünf Minuten), um Replays zu stoppen. Diese Seite ist ein Debugger, keine Referenzimplementierung; sie nutzt einen gewöhnlichen Vergleich, weil Timing-Angriffe gegen Ihren eigenen Browser kein Thema sind.
Fragen
Ist mein Secret hier sicher?
Der HMAC wird in Ihrem Browser mit WebCrypto berechnet, und die Seite macht keine Netzwerkanfragen. Nutzen Sie trotzdem ein Test-Endpunkt-Secret und rotieren Sie alles, was Sie in eine Webseite einfügen, wenn Sie streng sein wollen.
Warum sendet GitHub sowohl X-Hub-Signature als auch X-Hub-Signature-256?
Der erste ist HMAC-SHA1, für alte Integrationen behalten; der zweite ist HMAC-SHA256 und der, den Sie prüfen sollten. Beide gehen über den rohen Body mit demselben Secret.
Der erwartete Wert stimmt bis auf die Groß-/Kleinschreibung. Ist das ein Fehler?
Hex ist im Prüfcode jedes Anbieters unabhängig von der Schreibweise, also nein; dieses Tool vergleicht Hex ebenfalls schreibweisenunabhängig. Base64 unterscheidet Groß- und Kleinschreibung.
Stripe sagt, der Zeitstempel sei zu alt.
Stripes Bibliotheken lehnen Signaturen ab, deren t= mehr als 300 Sekunden von der aktuellen Zeit abweicht, um Replays zu verhindern. Eine später erneut abgespielte Anfrage scheitert deshalb, obwohl der HMAC korrekt ist; das Tool vermerkt das Alter.