Webhooks erklärt: Signierte Payloads und Retry-Strategien
Sie haben eine API erstellt, die Webhooks sendet, um externe Dienste über Ereignisse zu benachrichtigen. Aber was passiert, wenn der empfangende Endpunkt nicht erreichbar ist? Oder wenn ein böswilliger Akteur versucht, eine Webhook-Anfrage zu fälschen? Ohne geeignete Schutzmaßnahmen können Ihre Webhooks zu einer Quelle für Dateninkonsistenzen und Sicherheitslücken werden. Dieser Artikel erklärt, wie Sie signierte Payloads und Retry-Mechanismen implementieren, um Ihre Webhooks zuverlässig und sicher zu machen.
Was sind Webhooks und warum brauchen sie Sicherheit?
Webhooks sind benutzerdefinierte HTTP-Callbacks, die durch bestimmte Ereignisse ausgelöst werden. Sie ermöglichen die Echtzeitkommunikation zwischen Systemen, beispielsweise die Benachrichtigung eines Zahlungsdienstes, wenn eine Bestellung aufgegeben wird. Da Webhooks jedoch öffentlich zugängliche Endpunkte sind, sind sie anfällig für Spoofing und Replay-Angriffe. Darüber hinaus können Netzwerkprobleme oder Ausfälle beim Empfänger dazu führen, dass Ereignisse verloren gehen. Daher müssen zwei kritische Aspekte berücksichtigt werden: Authentizität (durch signierte Payloads) und Zuverlässigkeit (durch Wiederholungsversuche).
Signierte Payloads: Gewährleistung von Authentizität und Integrität
Ein signierter Payload ermöglicht es dem Empfänger zu überprüfen, ob der Webhook von einer vertrauenswürdigen Quelle stammt und die Daten nicht manipuliert wurden. Dies wird typischerweise durch HMAC (Hash-based Message Authentication Code) mit einem gemeinsam genutzten Geheimnis erreicht.
Wie HMAC-Signierung funktioniert
Sender und Empfänger teilen einen geheimen Schlüssel. Für jede Webhook-Anfrage berechnet der Sender eine HMAC-Signatur unter Verwendung des Geheimnisses und des Anfrage-Payloads (oft einschließlich eines Zeitstempels, um Replay-Angriffe zu verhindern). Die Signatur wird in einem Header gesendet, z. B. X-Signature. Der Empfänger berechnet die Signatur neu und vergleicht sie mit der empfangenen. Wenn sie übereinstimmen, ist die Anfrage authentisch.
Hier ist ein Beispiel in Python mit HMAC-SHA256:
import hmac
import hashlib
import time
secret = b'your_shared_secret'
payload = b'{"event":"order.created","id":123}'
timestamp = str(int(time.time())).encode()
message = timestamp + b'.' + payload
signature = hmac.new(secret, message, hashlib.sha256).hexdigest()
# Send headers: X-Signature: signature, X-Timestamp: timestamp
Auf der Empfängerseite überprüfen Sie die Signatur und prüfen den Zeitstempel, um sicherzustellen, dass die Anfrage aktuell ist (z. B. innerhalb von 5 Minuten). Dies verhindert Replay-Angriffe.
Best Practices für signierte Payloads
- Verwenden Sie ein starkes Geheimnis: Generieren Sie ein zufälliges Geheimnis mit hoher Entropie und speichern Sie es sicher.
- Fügen Sie einen Zeitstempel hinzu: Lehnen Sie Anfragen mit Zeitstempeln außerhalb eines akzeptablen Fensters ab.
- Verwenden Sie einen konstanten Zeitvergleich: Verhindern Sie Timing-Angriffe durch Funktionen wie
hmac.compare_digest. - Rotieren Sie Geheimnisse regelmäßig: Erlauben Sie während der Rotation mehrere aktive Geheimnisse.
Retry-Mechanismen: Gewährleistung einer zuverlässigen Zustellung
Selbst mit signierten Payloads können Netzwerkfehler oder Empfängerfehler dazu führen, dass die Webhook-Zustellung fehlschlägt. Eine robuste Retry-Strategie stellt sicher, dass Ereignisse letztendlich zugestellt werden, ohne den Empfänger zu überlasten.
Entwurf einer Retry-Richtlinie
Ein gängiger Ansatz ist exponentielles Backoff mit Jitter. Beispielsweise Wiederholung nach 1 Minute, dann 5 Minuten, dann 30 Minuten, bis zu einer maximalen Anzahl von Versuchen (z. B. 5). Fügen Sie eine eindeutige Ereignis-ID in den Payload ein, damit der Empfänger Duplikate erkennen kann.
Beispiel für einen Wiederholungsplan:
| Versuch | Verzögerung |
|---|---|
| 1 | Sofort |
| 2 | 1 Minute |
| 3 | 5 Minuten |
| 4 | 30 Minuten |
| 5 | 2 Stunden |
Nach Ausschöpfung der Wiederholungsversuche verschieben Sie das Ereignis in eine Dead-Letter-Queue zur manuellen Überprüfung.
Idempotenz: Umgang mit doppelten Zustellungen
Da Wiederholungsversuche zu doppelten Zustellungen führen können, müssen Empfänger idempotent sein. Fügen Sie eine Ereignis-ID in den Payload ein und lassen Sie den Empfänger verarbeitete IDs speichern, um Duplikate zu ignorieren. Alternativ können Sie Operationen so gestalten, dass sie von Natur aus idempotent sind (z. B. PUT anstelle von POST verwenden).
Implementierung von Webhooks: Eine Schritt-für-Schritt-Anleitung
- Definieren Sie Ereignisse und Payload-Struktur: Dokumentieren Sie die Ereignisse, die Ihr System ausgibt, und das JSON-Schema für jedes.
- Generieren Sie ein Geheimnis: Erstellen Sie ein eindeutiges Geheimnis pro Webhook-Endpunkt und teilen Sie es sicher.
- Signieren Sie jede Anfrage: Berechnen Sie HMAC über den Payload und den Zeitstempel und fügen Sie ihn in die Header ein.
- Implementieren Sie Wiederholungsversuche mit Backoff: Verwenden Sie ein Warteschlangensystem, um Wiederholungsversuche zu planen.
- Bieten Sie eine Möglichkeit zur Überprüfung von Signaturen: Dokumentieren Sie den Überprüfungsprozess für Empfänger.
- Überwachen und protokollieren Sie: Verfolgen Sie Zustellungsversuche und -fehler zur Fehlerbehebung.
Häufige Fallstricke und wie man sie vermeidet
- TLS ignorieren: Verwenden Sie immer HTTPS, um Payloads während der Übertragung zu schützen.
- Den Zeitstempel nicht validieren: Ermöglicht Replay-Angriffe.
- Unbegrenzte Wiederholungsversuche: Kann zu Ressourcenerschöpfung führen; legen Sie ein Maximum fest.
- Sofortige Zustellung annehmen: Entwerfen Sie für asynchrone Verarbeitung.
FAQ
Was ist ein signierter Webhook-Payload?
Ein signierter Webhook-Payload enthält eine kryptografische Signatur (z. B. HMAC), die es dem Empfänger ermöglicht, die Authentizität des Senders und die Datenintegrität zu überprüfen.
Wie oft sollte ich einen fehlgeschlagenen Webhook wiederholen?
Typischerweise 3 bis 5 Wiederholungen mit exponentiellem Backoff. Die genaue Anzahl hängt von Ihrem SLA und der Kritikalität des Ereignisses ab.
Kann ich JWT anstelle von HMAC für Webhook-Signaturen verwenden?
Ja, JWT kann verwendet werden, aber HMAC ist einfacher und üblicher für die Webhook-Signierung. JWT verursacht zusätzlichen Overhead und eignet sich besser für Authentifizierungs-Token.
Bereit, Ihre Webhook-Payloads zu testen? Verwenden Sie unseren JSON-Formatter, um Ihre JSON-Payloads vor dem Senden zu validieren und zu verschönern.