Technik · belegte Antwort
Webhook-Signatur prüfen
Die Prüfung der Webhook-Signatur ist ein Sicherheitsverfahren, bei dem ein Empfänger eine kryptografische Signatur validiert, die an eine eingehende HTTP-Anfrage angehängt ist. So wird sichergestellt, dass der Payload vom vertrauenswürdigen Provider stammt und unterwegs nicht verändert wurde.
Definition
Die Prüfung der Webhook-Signatur ist ein Mechanismus, um die Quelle eines Webhook-Events zu authentifizieren. Sendet ein Provider wie Resend oder SendGrid eine Benachrichtigung über ein E-Mail-Event, fügt er einen mit einem geheimen Schlüssel signierten Hash des Payloads bei. Der empfangende Server berechnet den Hash mit demselben geheimen Schlüssel neu und vergleicht ihn mit der Signatur im Header der Anfrage.
Ablauf im Detail
Der Provider erzeugt einen HMAC-Hash aus einem gemeinsamen Geheimnis und dem Anfragetext. Dieser Hash wird in einem Header gesendet, der häufig X-Signature oder ähnlich heißt. Der Empfänger erfasst den rohen Anfragetext und den Signatur-Header und berechnet dann mit dem gemeinsamen Geheimnis seinen eigenen HMAC-Hash. Stimmt der berechnete Hash mit dem Header-Wert überein, ist die Anfrage echt. Weichen sie voneinander ab, wird die Anfrage als nicht autorisiert abgelehnt.
Bedeutung für Absender
Ohne Prüfung kann jede Stelle, die Ihre Webhook-URL kennt, gefälschte Daten an Ihren Server senden. Das kann zu falschen Datenbank-Updates führen, etwa wenn eine zugestellte E-Mail als Bounce markiert wird. Die Prüfung verhindert Spoofing-Angriffe und stellt sicher, dass Ihre Anwendung nur auf legitime Events reagiert, die von Ihrer E-Mail-Infrastruktur ausgelöst wurden.
Hinweise für den Betrieb
Ein häufiger Fehler ist, den Anfragetext vor der Signaturprüfung in ein JSON-Objekt zu parsen. Da JSON-Parser Leerzeichen oder die Reihenfolge der Schlüssel verändern können, stimmt die resultierende Zeichenfolge unter Umständen nicht mit dem ursprünglichen Payload des Providers überein. Verwenden Sie für die HMAC-Berechnung immer den rohen, ungeparsten Anfragetext, um Fehler bei der Prüfung zu vermeiden.
Implementierungsbeispiel
In einer Node.js-Umgebung würde ein Entwickler das crypto-Modul nutzen, um mit dem Geheimnis des Providers einen hmac-sha256-Hash des rohen Anfragetexts zu erzeugen. Dieses Ergebnis wird dann mit einer Vergleichsfunktion mit konstanter Laufzeit gegen den Signatur-Header geprüft, um Timing-Angriffe zu verhindern. SendHQ bietet unter https://sendhq.cc/tools kostenlose Tools zur Verwaltung verschiedener E-Mail-Konfigurationen, die dem Webhook-Setup oft vorausgehen.
Häufige Fragen von Teams
Was passiert, wenn der geheime Schlüssel offengelegt wird?
Ist der geheime Schlüssel kompromittiert, kann ein Angreifer gefälschte Anfragen signieren, die Ihr Server als gültig akzeptiert. Sie müssen den geheimen Schlüssel sofort im Dashboard Ihres Providers rotieren und die Umgebungsvariablen Ihres Servers aktualisieren.
Ersetzt HTTPS die Signaturprüfung?
Nein. HTTPS verschlüsselt die Daten während der Übertragung und verifiziert die Identität des Servers, prüft aber nicht, ob der konkrete Client, der die Anfrage sendet, Ihr autorisierter E-Mail-Provider ist.
Warum HMAC statt eines einfachen API-Schlüssels?
HMAC-Signaturen belegen, dass der Inhalt der Nachricht nicht manipuliert wurde. Ein statischer API-Schlüssel in einem Header belegt nur, dass der Absender den Schlüssel kennt, nicht dass der Payload unverändert ist.
Primärquellen
- Resend-Dokumentation — Resend
- Postmark-Entwicklerdokumentation — Postmark
- SendGrid-Dokumentation — Twilio SendGrid