Webhooks erklärt: Signierte Payloads und Retries für zuverlässige Integrationen
Sie haben gerade einen Endpunkt zum Empfangen von Webhooks von einem Zahlungsanbieter erstellt. Der erste Test funktioniert einwandfrei, aber in der Produktion bemerken Sie fehlende Ereignisse, doppelte Abbuchungen und keine Möglichkeit festzustellen, ob eine Anfrage echt ist. Webhooks sind im Konzept einfach, aber schwierig richtig umzusetzen. Dieser Leitfaden erklärt, wie Sie Webhooks mit signierten Payloads absichern und robuste Retry-Logik implementieren, damit Ihre Integrationen nicht stillschweigend ausfallen.
Was sind Webhooks und warum sie wichtig sind
Webhooks sind benutzerdefinierte HTTP-Callbacks, die durch Ereignisse ausgelöst werden. Anstatt dass Ihre Anwendung eine API auf Änderungen abfragt, pusht der Dienst Daten an Ihren Endpunkt, wenn etwas passiert. Das macht Integrationen effizient und nahezu in Echtzeit.
Häufige Anwendungsfälle sind Zahlungsbenachrichtigungen (z. B. Stripe), CI/CD-Trigger (z. B. GitHub) und Messaging-Plattformen (z. B. Slack). Aber mit diesem Push-Modell verlieren Sie die Kontrolle darüber, wann Anfragen eintreffen. Deshalb müssen Sie Sicherheit und Zuverlässigkeit explizit behandeln.
Das Sicherheitsproblem: Unsigned Webhooks sind gefährlich
Ein unsignierter Webhook ist einfach ein HTTP-POST an eine öffentliche URL. Jeder kann eine Anfrage senden, die so aussieht, als käme sie von Ihrem Zahlungsanbieter. Ohne Verifizierung könnten Angreifer Ereignisse fälschen, was zu betrügerischen Bestellungen, Datenlecks oder unbefugten Aktionen führen kann.
Die Lösung besteht darin, den Payload zu signieren. Der Sender berechnet eine kryptografische Signatur über den Request-Body mit einem gemeinsamen Secret und fügt sie in einen Header ein. Ihr Endpunkt berechnet die Signatur neu und vergleicht sie. Wenn sie übereinstimmen, wissen Sie, dass die Anfrage authentisch ist und nicht manipuliert wurde.
So signieren Sie Webhook-Payloads mit HMAC
HMAC (Hash-based Message Authentication Code) ist der Standard für die Webhook-Signierung. Es verwendet einen geheimen Schlüssel und eine Hash-Funktion (wie SHA-256), um eine Signatur zu erzeugen, die eindeutig für den Payload und das Secret ist.
So könnte ein Sender einen Payload in Python signieren:
import hmac
import hashlib
import json
secret = b'your_shared_secret'
payload = json.dumps({'event': 'payment.success', 'amount': 1000}).encode('utf-8')
signature = hmac.new(secret, payload, hashlib.sha256).hexdigest()
# Include signature in header: X-Signature:
Auf der Empfängerseite müssen Sie die Signatur überprüfen, bevor Sie den Payload verarbeiten:
import hmac
import hashlib
def verify_signature(payload, received_signature, secret):
expected = hmac.new(secret, payload, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, received_signature)
Wichtig: Verwenden Sie immer eine Vergleichsfunktion mit konstanter Zeit wie hmac.compare_digest, um Timing-Angriffe zu verhindern. Überprüfen Sie die Signatur außerdem gegen den rohen Request-Body, nicht gegen eine geparste Version, da die JSON-Serialisierung abweichen kann.
Best Practices für signierte Payloads
- Verwenden Sie ein starkes Secret: Generieren Sie ein zufälliges Secret von mindestens 32 Bytes und speichern Sie es sicher (z. B. Umgebungsvariable oder Secrets Manager).
- Fügen Sie einen Zeitstempel hinzu: Fügen Sie dem signierten Payload einen Zeitstempel hinzu und lehnen Sie Anfragen ab, die älter als ein paar Minuten sind, um Replay-Angriffe zu verhindern.
- Verwenden Sie HTTPS: Übertragen Sie Webhooks immer über TLS, um Payload und Signatur während der Übertragung zu schützen.
- Rotieren Sie Secrets regelmäßig: Unterstützen Sie während der Rotation mehrere aktive Secrets, um Ausfallzeiten zu vermeiden.
Fehlerbehandlung: Retries und Idempotenz
Webhooks können fehlschlagen: Ihr Server könnte ausgefallen sein, das Netzwerk könnte ausfallen oder Ihr Endpunkt könnte einen Fehler zurückgeben. Ein zuverlässiger Sender wird die Zustellung wiederholen, aber Sie müssen Ihren Empfänger so gestalten, dass er Duplikate und Ereignisse außerhalb der Reihenfolge verarbeiten kann.
Retry-Strategien
Die meisten Webhook-Anbieter verwenden exponentielles Backoff mit Jitter. Zum Beispiel: Wiederholung nach 1 Minute, dann 5 Minuten, dann 30 Minuten, bis zu einer maximalen Anzahl von Versuchen. Dies gibt Ihrem System Zeit zur Erholung, ohne es zu überlasten.
Wenn Sie die Senderseite erstellen, implementieren Sie eine Warteschlange mit geplanten Wiederholungen. Speichern Sie den Payload und die Versuchsanzahl und verwenden Sie einen Worker zur Verarbeitung der Wiederholungen.
Idempotenz: Der Schlüssel für sichere Retries
Da Wiederholungen zu doppelten Zustellungen führen können, muss Ihr Endpunkt idempotent sein. Das bedeutet, dass die mehrfache Verarbeitung desselben Ereignisses dieselbe Wirkung haben sollte wie die einmalige Verarbeitung.
Häufige Ansätze:
- Verwenden Sie eine eindeutige Ereignis-ID: Fügen Sie eine ID in den Payload ein und speichern Sie verarbeitete IDs in einer Datenbank. Ignorieren Sie Ereignisse mit IDs, die Sie bereits gesehen haben.
- Gestalten Sie Operationen idempotent: Verwenden Sie beispielsweise Upserts statt Inserts oder prüfen Sie, ob eine Ressource bereits existiert, bevor Sie sie erstellen.
Hier ist eine einfache Idempotenz-Prüfung in Python:
def process_event(event_id, payload):
if db.exists('processed_events', event_id):
return # already processed
# process payload
db.insert('processed_events', event_id)
Stellen Sie sicher, dass die Prüfung und die Verarbeitung in einer einzigen Transaktion erfolgen, um Race Conditions zu vermeiden.
Vergleich: Polling vs. Webhooks
| Aspekt | Polling | Webhooks |
|---|---|---|
| Latenz | Abhängig vom Intervall (z. B. 5 Min.) | Nahezu Echtzeit |
| Serverlast | Konstante Anfragen auch ohne Änderungen | Anfragen nur bei Ereignissen |
| Komplexität | Einfach zu implementieren | Erfordert Signierung, Retries, Idempotenz |
| Zuverlässigkeit | Sie kontrollieren die Wiederholungen | Abhängig von der Retry-Richtlinie des Senders |
Schritt für Schritt: Implementierung eines sicheren Webhook-Empfängers
- Richten Sie einen HTTPS-Endpunkt ein, der POST-Anfragen akzeptiert und den rohen Body liest.
- Extrahieren Sie den Signatur-Header (z. B.
X-Signature) und den Zeitstempel-Header, falls vorhanden. - Überprüfen Sie die Signatur mit HMAC und Ihrem Secret. Lehnen Sie bei Ungültigkeit ab.
- Prüfen Sie den Zeitstempel, um Replay-Angriffe zu verhindern (z. B. ablehnen, wenn älter als 5 Minuten).
- Parsen Sie den Payload und extrahieren Sie die Ereignis-ID.
- Prüfen Sie die Idempotenz, indem Sie die Ereignis-ID in Ihrer Datenbank nachschlagen.
- Verarbeiten Sie das Ereignis innerhalb einer Transaktion, die auch die Ereignis-ID aufzeichnet.
- Geben Sie schnell einen 2xx-Status zurück, um den Empfang zu bestätigen. Wenn die Verarbeitung Zeit in Anspruch nimmt, reihen Sie den Job ein und geben Sie 202 Accepted zurück.
Testen Ihrer Webhook-Implementierung
Verwenden Sie Tools wie ngrok, um Ihren lokalen Server verfügbar zu machen und Webhooks zu simulieren. Schreiben Sie Unit-Tests für Signaturverifizierung, Idempotenz und Retry-Logik. Testen Sie beispielsweise, dass eine doppelte Ereignis-ID ignoriert wird und dass eine ungültige Signatur 401 zurückgibt.
Protokollieren Sie beim Debuggen den empfangenen Payload und die Signatur (aber niemals Secrets). Wenn Sie mit JSON-Payloads arbeiten, kann ein JSON-Formatter Ihnen helfen, die Struktur schnell zu inspizieren und zu validieren.
FAQ
Was ist ein signierter Webhook-Payload?
Ein signierter Payload enthält eine kryptografische Signatur (normalerweise HMAC), die über den Request-Body mit einem gemeinsamen Secret berechnet wird. Der Empfänger überprüft die Signatur, um sicherzustellen, dass die Anfrage authentisch und unverändert ist.
Wie oft sollte ein Webhook wiederholt werden?
Es gibt keine allgemeingültige Zahl, aber üblich sind 3–5 Wiederholungen mit exponentiellem Backoff. Danach wird das Ereignis oft als fehlgeschlagen markiert und erfordert möglicherweise manuelle Eingriffe oder eine Dead-Letter-Queue.
Kann ich Webhooks ohne HTTPS verwenden?
Sie sollten Webhooks niemals über einfaches HTTP verwenden. Ohne TLS können Angreifer den Payload und die Signatur abfangen und Anfragen wiederholen oder ändern. Verwenden Sie immer HTTPS.
Bereit, Webhook-Payloads zu inspizieren und zu formatieren? Probieren Sie unseren kostenlosen JSON-Formatter, um JSON-Daten sofort zu validieren und zu verschönern.