Webhooks erklärt: Signierte Payloads und Retries für zuverlässige Integrationen

Backend2026-11-13TryQuickToolBox

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

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:

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

AspektPollingWebhooks
LatenzAbhängig vom Intervall (z. B. 5 Min.)Nahezu Echtzeit
ServerlastKonstante Anfragen auch ohne ÄnderungenAnfragen nur bei Ereignissen
KomplexitätEinfach zu implementierenErfordert Signierung, Retries, Idempotenz
ZuverlässigkeitSie kontrollieren die WiederholungenAbhängig von der Retry-Richtlinie des Senders

Schritt für Schritt: Implementierung eines sicheren Webhook-Empfängers

  1. Richten Sie einen HTTPS-Endpunkt ein, der POST-Anfragen akzeptiert und den rohen Body liest.
  2. Extrahieren Sie den Signatur-Header (z. B. X-Signature) und den Zeitstempel-Header, falls vorhanden.
  3. Überprüfen Sie die Signatur mit HMAC und Ihrem Secret. Lehnen Sie bei Ungültigkeit ab.
  4. Prüfen Sie den Zeitstempel, um Replay-Angriffe zu verhindern (z. B. ablehnen, wenn älter als 5 Minuten).
  5. Parsen Sie den Payload und extrahieren Sie die Ereignis-ID.
  6. Prüfen Sie die Idempotenz, indem Sie die Ereignis-ID in Ihrer Datenbank nachschlagen.
  7. Verarbeiten Sie das Ereignis innerhalb einer Transaktion, die auch die Ereignis-ID aufzeichnet.
  8. 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.