Alles Wissenswerte, nichts Unwissendes.
Wie die Signatur aufgebaut ist
Eine gängige Konstruktion bildet den kanonischen String als `${timestamp}.${requestBody}`, berechnet `HMAC-SHA256(canonical, secret)`, kodiert das Ergebnis hexadezimal und sendet Digest und Zeitstempel in einem Signatur-Header. Der Zeitstempel in der signierten Nutzlast verhindert Replay-Angriffe – Ihr Endpunkt sollte Webhooks ablehnen, die älter als 5 Minuten sind. Header-Namen und das genaue kanonische Format unterscheiden sich je nach Plattform; klären Sie sie daher mit Ihrem Anbieter, bevor Sie Verifizierungscode schreiben.
Warum HMAC- und nicht RSA-Signaturen?
HMAC ist symmetrisch – beide Seiten teilen sich ein Geheimnis –, wodurch Signierung und Verifizierung etwa 10.000-mal schneller sind als mit RSA-2048. Bei Webhook-Fan-Out, wo ein einzelner SMSC bis zu 50.000 DLRs pro Sekunde ausgibt, dominiert die RSA-Signierung die CPU-Auslastung. HMAC-SHA256 benötigt auf moderner Hardware nur wenige Mikrosekunden. Der Vorteil: Jeder, der das Geheimnis kennt, kann signieren. Das Geheimnis sollte daher nur zwischen der Plattform und Ihrer Umgebung geteilt, wie jede andere Zugangsinformation gespeichert und bei Bedarf rotiert werden.
Fallstricke bei der Verifizierung
Drei häufige Fehler: 1. Der Vergleich von Zeichenketten mit `==` anstelle eines Vergleichs mit konstanter Laufzeit (Timing-Angriff – verwenden Sie `crypto.timingSafeEqual`). 2. Die Validierung der Signatur nach dem JSON-Parsing des Bodys (Sie müssen die Rohbytes überprüfen, nicht eine neu serialisierte Darstellung – eine Neuanordnung in JSON führt zu einem fehlerhaften Hash). 3. Das Vergessen des Zeitstempel-Anti-Replay-Fensters.
Jenseits von HMAC
Für regulierte Umgebungen (Banken, Gesundheitswesen) unterstützen manche Plattformen zusätzlich die Webhook-Zustellung per mTLS – der Absender legt ein Client-Zertifikat vor, das Ihr Load-Balancer prüft, bevor die Anfrage die Anwendung erreicht. Das ist stärker als HMAC, weil die Zustellung an einen Hardware-Schlüssel gebunden ist, lohnt sich aber nur für wirklich sensible Workloads. Für die meisten Integrationen ist HMAC-SHA256 über HTTPS die richtige Wahl.