Webhooks erklärt: Signierte Payloads und Retries
Sie haben eine API erstellt und müssen nun andere Dienste benachrichtigen, wenn Ereignisse eintreten. Polling ist ineffizient, also implementieren Sie Webhooks. Aber bald stellen Sie fest: Wie stellen Sie sicher, dass die Payload authentisch ist? Was ist, wenn der Empfänger nicht erreichbar ist? Ohne geeignete Schutzmaßnahmen können Webhooks zu einem Sicherheitsloch und einem Zuverlässigkeitsalbtraum werden.
In diesem Artikel gehen wir auf die Grundlagen von Webhooks ein und konzentrieren uns auf zwei kritische Aspekte: signierte Payloads für die Sicherheit und Wiederholungsmechanismen für die Zuverlässigkeit. Wir bieten praktische Codebeispiele und Best Practices, damit Sie robuste Webhook-Systeme erstellen können.
Was sind Webhooks?
Webhooks sind benutzerdefinierte HTTP-Callbacks. Sie ermöglichen es einem System, Echtzeitdaten an ein anderes zu senden, wenn ein bestimmtes Ereignis eintritt. Im Gegensatz zu APIs, bei denen Sie Daten abrufen, pushen Webhooks Daten zu Ihnen. Das macht sie ideal für ereignisgesteuerte Architekturen.
Häufige Anwendungsfälle sind Zahlungsbenachrichtigungen (z. B. Stripe), CI/CD-Trigger (z. B. GitHub) und Messaging-Plattformen (z. B. Slack). Der Absender führt eine HTTP-POST-Anfrage an eine vom Empfänger bereitgestellte URL aus, mit einer Payload, die Ereignisdetails enthält.
Warum Webhooks mit signierten Payloads absichern?
Webhook-Endpunkte sind öffentlich zugänglich und daher anfällig für Spoofing. Ein Angreifer könnte gefälschte Payloads senden, um unbeabsichtigte Aktionen auszulösen. Um dies zu verhindern, signieren Absender die Payload mit einem gemeinsamen Secret. Der Empfänger überprüft die Signatur, um Authentizität und Integrität sicherzustellen.
Das Signieren umfasst typischerweise die Generierung eines HMAC (Hash-based Message Authentication Code) der Payload unter Verwendung eines geheimen Schlüssels. Die Signatur wird in einem Header gesendet (z. B. X-Signature). Der Empfänger berechnet den HMAC neu und vergleicht ihn mit der empfangenen Signatur.
So implementieren Sie signierte Payloads
Sehen wir uns ein einfaches Beispiel in Python mit Flask an. Der Absender berechnet die Signatur:
import hmac
import hashlib
import json
import requests
secret = b'your_shared_secret'
payload = {'event': 'payment.success', 'amount': 100}
body = json.dumps(payload).encode('utf-8')
signature = hmac.new(secret, body, hashlib.sha256).hexdigest()
headers = {'Content-Type': 'application/json', 'X-Signature': signature}
requests.post('https://receiver.com/webhook', data=body, headers=headers)
Der Empfänger überprüft die Signatur:
from flask import Flask, request, abort
import hmac
import hashlib
app = Flask(__name__)
secret = b'your_shared_secret'
@app.route('/webhook', methods=['POST'])
def webhook():
signature = request.headers.get('X-Signature')
body = request.get_data()
expected = hmac.new(secret, body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(signature, expected):
abort(401)
# Process payload
return '', 200
Best Practices:
- Verwenden Sie ein starkes Secret und rotieren Sie es regelmäßig.
- Fügen Sie einen Zeitstempel in die signierten Daten ein, um Replay-Angriffe zu verhindern.
- Verwenden Sie
hmac.compare_digestfür einen konstanten Zeitvergleich. - Signieren Sie den Rohbody, nicht das geparste JSON, um Inkonsistenzen zu vermeiden.
Zuverlässige Wiederholungsversuche implementieren
Die Webhook-Zustellung kann aufgrund von Netzwerkproblemen, Ausfallzeiten des Empfängers oder Verarbeitungsfehlern fehlschlagen. Ein robustes System sollte fehlgeschlagene Zustellungen mit exponentiellem Backoff wiederholen.
Retry-Strategie
Üblicher Ansatz: Wiederholen Sie bis zu N-mal mit zunehmenden Verzögerungen (z. B. 1s, 5s, 30s, 5m, 30m). Nach Ausschöpfung der Wiederholungen markieren Sie die Zustellung als fehlgeschlagen und alarmieren.
Hier ist ein einfacher Wiederholungsmechanismus in Python unter Verwendung der Bibliotheken requests und tenacity:
from tenacity import retry, stop_after_attempt, wait_exponential
import requests
@retry(stop=stop_after_attempt(5), wait=wait_exponential(multiplier=1, min=1, max=60))
def send_webhook(url, payload, signature):
headers = {'X-Signature': signature}
response = requests.post(url, json=payload, headers=headers, timeout=10)
response.raise_for_status()
return response
Best Practices für Wiederholungsversuche:
- Verwenden Sie Idempotenzschlüssel, damit Empfänger deduplizieren können.
- Legen Sie für jede Anfrage ein Timeout fest, um Hängenbleiben zu vermeiden.
- Protokollieren Sie jeden Versuch zum Debuggen.
- Bieten Sie eine Möglichkeit, manuell über ein Dashboard erneut zu versuchen.
Vergleich: Signierte Payloads vs. Basic Auth
| Ansatz | Sicherheit | Komplexität | Replay-Schutz |
|---|---|---|---|
| Basic Auth | Niedrig (Anmeldeinformationen werden jedes Mal gesendet) | Niedrig | Nein |
| Signierte Payload (HMAC) | Hoch | Mittel | Ja (mit Zeitstempel) |
Schritt für Schritt: Erstellen eines Webhook-Senders mit Wiederholungsversuchen
- Definieren Sie die Ereignis-Payload und fügen Sie eine eindeutige Ereignis-ID und einen Zeitstempel hinzu.
- Berechnen Sie die Signatur mit HMAC-SHA256 über den Rohbody.
- Senden Sie die Anfrage mit der Signatur in einem Header.
- Behandeln Sie Fehler durch Wiederholungsversuche mit exponentiellem Backoff.
- Protokollieren Sie Zustellungen und bieten Sie Transparenz.
Webhooks testen
Verwenden Sie Tools wie ngrok, um Ihren lokalen Server verfügbar zu machen und die Webhook-Zustellung zu testen. Überprüfen Sie in Ihren Tests immer die Signaturen, um Probleme frühzeitig zu erkennen.
FAQ
Was ist eine signierte Payload in Webhooks?
Eine signierte Payload ist eine Webhook-Anfrage, bei der der Absender eine kryptografische Signatur (normalerweise HMAC) hinzufügt, die mit einem gemeinsamen Secret generiert wurde. Der Empfänger überprüft die Signatur, um zu bestätigen, dass die Anfrage authentisch ist und nicht manipuliert wurde.
Wie oft sollte ich einen fehlgeschlagenen Webhook wiederholen?
Es gibt keine feste Anzahl, aber üblich sind 3 bis 5 Wiederholungen mit exponentiellem Backoff. Berücksichtigen Sie die typische Ausfallzeit Ihres Empfängers und die Kritikalität des Ereignisses. Erlauben Sie immer manuelle Wiederholungen.
Kann ich JWT für Webhook-Signaturen verwenden?
Ja, JWT kann verwendet werden, ist aber komplexer. HMAC-Signaturen sind einfacher und für die meisten Fälle ausreichend. Wenn Sie Claims einbeziehen müssen, könnte JWT geeignet sein.
Bereit, Ihre Webhook-Payloads zu testen? Verwenden Sie unseren JSON Formatter, um Ihre JSON-Payloads vor dem Senden zu validieren und hübsch zu formatieren.