Webhooks erklärt: Signierte Payloads und Retries

Sie haben gerade einen Drittanbieterdienst integriert, der Webhooks an Ihren Endpunkt sendet. Im Test funktioniert alles, aber in der Produktion stellen Sie verpasste Ereignisse, doppelte Zustellungen und gelegentliche Sicherheitsbedenken fest. Webhooks sind im Konzept einfach, aber in der Praxis knifflig – besonders wenn es um die Überprüfung der Authentizität und die Behandlung von Fehlern geht.

Dieser Leitfaden erklärt, wie Sie Webhooks mit signierten Payloads absichern und robuste Retry-Mechanismen implementieren, damit Sie zuverlässige Integrationen erstellen können.

Was sind Webhooks?

Webhooks sind benutzerdefinierte HTTP-Callbacks. Wenn ein Ereignis in einem Quellsystem auftritt (z. B. eine Zahlung abgeschlossen wird), sendet es eine HTTP-POST-Anfrage an eine von Ihnen angegebene URL, die Daten über das Ereignis enthält. Dies ermöglicht Echtzeitkommunikation zwischen Diensten ohne Polling.

Aber Webhooks bringen Herausforderungen mit sich: Woher wissen Sie, dass die Anfrage wirklich vom erwarteten Absender stammt? Was ist, wenn Ihr Endpunkt vorübergehend nicht erreichbar ist? Hier kommen signierte Payloads und Retries ins Spiel.

Webhooks mit signierten Payloads absichern

Ein signierter Payload verwendet eine kryptografische Signatur, um zu beweisen, dass die Anfrage vom Absender stammt und nicht manipuliert wurde. Der gängige Ansatz ist HMAC (Hash-based Message Authentication Code) mit einem gemeinsamen Geheimnis.

Wie HMAC-Signaturen funktionieren

Der Absender berechnet einen HMAC über den Anforderungstext (und manchmal Header wie Zeitstempel) mit einem geheimen Schlüssel. Die Signatur wird in einem Header gesendet (z. B. X-Signature). Ihr Server berechnet den HMAC neu und vergleicht ihn mit der empfangenen Signatur. Wenn sie übereinstimmen, ist die Anfrage authentisch.

Hier ist ein minimales Beispiel in Python mit Flask:

import hmac
import hashlib
from flask import Flask, request, abort

app = Flask(__name__)
SECRET = b'your_shared_secret'

@app.route('/webhook', methods=['POST'])
def webhook():
    signature = request.headers.get('X-Signature')
    if not signature:
        abort(400, 'Missing signature')
    body = request.get_data()
    expected = hmac.new(SECRET, body, hashlib.sha256).hexdigest()
    if not hmac.compare_digest(expected, signature):
        abort(401, 'Invalid signature')
    # Process the event
    return '', 200

Wichtige Punkte:

• Verwenden Sie immer eine Vergleichsfunktion mit konstanter Zeit (wie hmac.compare_digest), um Timing-Angriffe zu verhindern.
• Fügen Sie einen Zeitstempel in die signierten Daten ein, um Replay-Angriffe zu verhindern; lehnen Sie Anfragen ab, die älter als ein paar Minuten sind.
• Halten Sie das Geheimnis sicher – geben Sie es niemals clientseitig preis.

Zusätzliche Sicherheitsmaßnahmen

• HTTPS: Verwenden Sie immer HTTPS, um den Payload während der Übertragung zu schützen.
• IP-Allowlisting: Wenn der Anbieter IP-Bereiche veröffentlicht, beschränken Sie Anfragen auf diese IPs.
• Idempotenz: Verwenden Sie Ereignis-IDs zur Deduplizierung, da Retries Duplikate verursachen können.

Zuverlässige Retries implementieren

Webhook-Consumer können ausfallen: Ihr Server könnte nicht erreichbar sein oder die Verarbeitung könnte in eine Zeitüberschreitung laufen. Absender sollten fehlgeschlagene Zustellungen mit exponentiellem Backoff wiederholen. Als Consumer müssen Sie Retries ordnungsgemäß behandeln.

Auf der Absenderseite (Wenn Sie ein Webhook-System erstellen)

1. Schnell 2xx zurückgeben: Bestätigen Sie den Empfang vor der Verarbeitung, um Zeitüberschreitungen zu vermeiden. Verwenden Sie eine Warteschlange für asynchrone Arbeit.
2. Bei Fehler wiederholen: Wenn innerhalb einer Zeitüberschreitung (z. B. 5 Sekunden) kein 2xx empfangen wird, wiederholen Sie mit zunehmenden Verzögerungen (z. B. 1s, 5s, 30s, 5m, 30m).
3. Retries begrenzen: Nach einer maximalen Anzahl von Versuchen (z. B. 5) markieren Sie die Zustellung als fehlgeschlagen und alarmieren Sie.
4. Fügen Sie eine eindeutige Ereignis-ID hinzu: Damit Consumer deduplizieren können.

Auf der Consumer-Seite (Ihr Endpunkt)

• Schnell antworten: Geben Sie sofort 2xx zurück und verarbeiten Sie asynchron, falls nötig.
• Idempotent sein: Verwenden Sie die Ereignis-ID, um zu vermeiden, dass dasselbe Ereignis zweimal verarbeitet wird.
• Duplikate behandeln: Speichern Sie verarbeitete Ereignis-IDs für einen angemessenen Zeitraum.
• Fehler protokollieren: Wenn die Verarbeitung fehlschlägt, geben Sie 5xx zurück, um einen Retry auszulösen, aber stellen Sie sicher, dass Sie nicht in einer Schleife feststecken.

Vergleich: Signierte Payloads vs. Basic Auth

Webhooks lokal testen

Während der Entwicklung benötigen Sie eine öffentliche URL, um Webhooks zu empfangen. Tools wie ngrok oder localtunnel können Ihren lokalen Server verfügbar machen. Testen Sie immer die Signaturverifikation und das Retry-Verhalten mit simulierten Fehlern.

Bei der Inspektion von Webhook-Payloads müssen Sie möglicherweise JSON für die Lesbarkeit formatieren. Der JSON Formatter kann Ihnen helfen, den JSON-Body übersichtlich zu formatieren und zu validieren.

FAQ

Was ist ein signierter Webhook-Payload?

Ein signierter Payload enthält eine kryptografische Signatur (oft HMAC), die es dem Empfänger ermöglicht, die Authentizität und Integrität der Anfrage zu überprüfen.

Wie oft sollte ein Webhook wiederholt werden?

Es gibt keine feste Anzahl; gängige Praktiken reichen von 3 bis 10 Wiederholungen mit exponentiellem Backoff. Der Schlüssel liegt darin, Zuverlässigkeit mit Ressourcennutzung in Einklang zu bringen und bei anhaltenden Fehlern zu alarmieren.

Kann ich Webhooks ohne Signaturen verwenden?

Es wird nicht empfohlen. Ohne Signaturen können Sie den Absender nicht verifizieren, was Ihren Endpunkt anfällig für Spoofing macht. Verwenden Sie in der Produktion immer Signaturen.

Bereit, Ihre Webhook-Payloads zu debuggen? Probieren Sie unseren JSON Formatter, um JSON-Daten schnell zu validieren und zu formatieren.