Webhooks erklärt: Signierte Payloads und Retries

Warum Webhooks sowohl leistungsstark als auch fragil sind

Webhooks ermöglichen Echtzeit-Integrationen: Zahlungsbenachrichtigungen, CI/CD-Trigger, Chat-Nachrichten. Sie bringen jedoch zwei große Herausforderungen mit sich: Sicherheit (Woher weißt du, dass die Anfrage vom erwarteten Absender stammt?) und Zuverlässigkeit (Was, wenn der Empfänger nicht erreichbar ist?). Dieser Artikel zeigt dir, wie du beide mit signierten Payloads und Retry-Strategien angehst.

Was ist ein Webhook?

Ein Webhook ist eine HTTP-POST-Anfrage, die von einem Anbieter an einen Konsumenten gesendet wird, wenn ein Ereignis eintritt. Im Gegensatz zum Polling übertragen Webhooks Daten nahezu in Echtzeit, was Latenz und Serverlast reduziert. Der Anbieter muss sicherstellen, dass die Anfrage authentisch ist; der Konsument muss sie zuverlässig verarbeiten.

Webhooks mit signierten Payloads absichern

Ein signierter Payload verwendet einen geheimen Schlüssel, um eine kryptografische Signatur (normalerweise HMAC-SHA256) des Anfrage-Bodys zu erstellen. Der Empfänger berechnet die Signatur neu und vergleicht sie mit der im Header. Wenn sie übereinstimmen, ist der Payload authentisch und unverändert.

Wie man Signaturen generiert und verifiziert

Hier ist ein typischer Ablauf:

1. Anbieter und Konsument teilen einen geheimen Schlüssel (z. B. über ein Dashboard).
2. Der Anbieter berechnet HMAC-SHA256(secret, payload) und sendet sie in einem Header wie X-Signature.
3. Der Konsument liest den Roh-Body, berechnet denselben HMAC und vergleicht ihn mit einer zeitkonstanten Funktion.

Beispiel in Node.js:

const crypto = require('crypto');

function verifySignature(secret, payload, signature) {
  const hmac = crypto.createHmac('sha256', secret);
  hmac.update(payload);
  const digest = hmac.digest('hex');
  return crypto.timingSafeEqual(Buffer.from(digest), Buffer.from(signature));
}

Verwende immer einen zeitkonstanten Vergleich, um Timing-Angriffe zu verhindern. Parse den Body niemals vor der Verifizierung – nutze Raw-Body-Middleware.

Retries für zuverlässige Zustellung implementieren

Selbst mit Signaturen können Netzwerkfehler oder vorübergehende Ausfälle dazu führen, dass die Webhook-Zustellung fehlschlägt. Ein robuster Retry-Mechanismus gewährleistet die letztendliche Zustellung.

Retry-Strategien

• Exponentielles Backoff: Warte länger zwischen jedem Wiederholungsversuch (z. B. 1s, 2s, 4s, 8s).
• Maximale Versuche: Begrenze die Wiederholungen (z. B. 5 Versuche), um Endlosschleifen zu vermeiden.
• Dead-Letter-Queue: Nach maximalen Versuchen speichere das Ereignis zur manuellen Überprüfung.
• Idempotenz: Füge eine eindeutige Event-ID hinzu, damit der Konsument Duplikate ignorieren kann.

Beispiel für Retry-Logik in Python:

import time
import requests

def send_webhook(url, payload, max_retries=5):
    for attempt in range(max_retries):
        try:
            response = requests.post(url, json=payload, timeout=5)
            if response.status_code == 200:
                return True
        except requests.RequestException:
            pass
        time.sleep(2 ** attempt)  # exponentielle Verzögerung
    return False

Best Practices für Webhook-Konsumenten

• Antworte schnell mit 2xx; verarbeite asynchron, falls nötig.
• Validiere die Signatur vor jeglicher Verarbeitung.
• Verwende Idempotenzschlüssel, um doppelte Zustellungen zu handhaben.
• Protokolliere alle eingehenden Webhooks zum Debuggen.
• Überwache Fehler und alarmiere bei wiederholten Fehlern.

Vergleich: Polling vs. Webhooks

FAQ

Was ist ein signierter Webhook-Payload?

Ein signierter Payload enthält eine kryptografische Signatur (z. B. HMAC), die es dem Empfänger ermöglicht zu überprüfen, dass die Anfrage von einer vertrauenswürdigen Quelle stammt und nicht manipuliert wurde.

Wie oft sollte ich einen fehlgeschlagenen Webhook wiederholen?

Es gibt keine allgemeingültige Zahl, aber 3–5 Versuche mit exponentiellem Backoff sind üblich. Danach protokolliere das Ereignis zur manuellen Überprüfung.

Kann ich JWT anstelle von HMAC für Webhook-Signaturen verwenden?

Ja, einige Anbieter verwenden JWT. Das Prinzip ist dasselbe: Überprüfe die Signatur und die Claims des Tokens, bevor du dem Payload vertraust.

Möchtest du Webhook-Payloads oder Logs inspizieren? Probiere unseren JSON Formatter, um JSON-Payloads schnell zu formatieren und zu validieren.