Webhooks erklärt: Signierte Payloads und Retry-Strategien

Sie haben gerade einen Webhook-Endpunkt erstellt, um Ereignisse von einem Drittanbieterdienst zu empfangen. In Tests funktioniert alles, aber in der Produktion stellen Sie fest, dass einige Ereignisse nie ankommen oder, schlimmer noch, Sie doppelte Ereignisse erhalten, die zu Dateninkonsistenzen führen. Dies sind klassische Webhook-Fallstricke, die auf zwei kritische Aspekte zurückzuführen sind: die Authentizität der Payload und die Zuverlässigkeit der Zustellung.

Webhooks sind HTTP-Callbacks, die durch Ereignisse ausgelöst werden und Daten in Echtzeit an Ihre Anwendung pushen. Im Gegensatz zum Polling sind sie effizient und nahezu sofort. Sie bringen jedoch Herausforderungen mit sich: Woher wissen Sie, dass die Anfrage wirklich vom erwarteten Absender stammt, und wie gehen Sie mit Fehlern um, wenn der Empfänger vorübergehend nicht erreichbar ist? Dieser Artikel befasst sich mit signierten Payloads und Retry-Mechanismen und gibt Ihnen praktische Muster an die Hand, um widerstandsfähige Webhook-Integrationen aufzubauen.

Warum Webhooks Signaturen benötigen

Webhook-Endpunkte sind öffentlich zugängliche URLs. Ohne Verifizierung kann jeder gefälschte Anfragen an Ihren Endpunkt senden und möglicherweise unbefugte Aktionen auslösen oder Daten beschädigen. Signierte Payloads lösen dieses Problem, indem sie jeder Anfrage eine kryptografische Signatur hinzufügen, mit der Sie die Identität des Absenders überprüfen und sicherstellen können, dass die Payload nicht manipuliert wurde.

Die meisten Anbieter verwenden HMAC (Hash-based Message Authentication Code) mit einem gemeinsamen Geheimnis. Der Absender berechnet einen Hash der Payload mit dem Geheimnis und fügt ihn in einen Header ein. Sie berechnen den Hash auf Ihrer Seite neu und vergleichen ihn. Wenn sie übereinstimmen, ist die Anfrage legitim.

Implementierung der HMAC-Verifizierung

Gehen wir eine typische Implementierung in Node.js durch. Angenommen, der Anbieter sendet eine Signatur im Header X-Signature, die als HMAC-SHA256 des rohen Request-Bodys mit Ihrem Geheimnis berechnet wird.

const crypto = require('crypto');
const express = require('express');
const app = express();

// Verwenden Sie einen Raw-Body-Parser, um die exakte Payload zu erhalten
app.use(express.raw({ type: 'application/json' }));

app.post('/webhook', (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  
  const expected = crypto
    .createHmac('sha256', secret)
    .update(req.body)
    .digest('hex');
  
  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }
  
  // Ereignis verarbeiten
  const event = JSON.parse(req.body);
  // ... Ereignis behandeln
  
  res.status(200).send('OK');
});

Wichtige Punkte:

• Verwenden Sie für die Verifizierung immer den rohen Request-Body, nicht das geparste JSON. Das Parsen kann Leerzeichen oder die Reihenfolge der Schlüssel ändern und den Hash brechen.
• Verwenden Sie einen zeitkonstanten Vergleich, um Timing-Angriffe zu verhindern.
• Halten Sie Ihr Geheimnis sicher; rotieren Sie es regelmäßig und unterstützen Sie mehrere aktive Geheimnisse während der Rotation.

Entwurf einer Retry-Strategie

Auch mit Signaturen können Zustellungen aufgrund von Netzwerkproblemen, Serverausfällen oder Timeouts fehlschlagen. Eine robuste Retry-Strategie stellt die eventuelle Zustellung sicher, ohne Ihr System oder den Absender zu überlasten.

1. Schnell bestätigen, asynchron verarbeiten

Ihr Webhook-Endpunkt sollte so schnell wie möglich mit einem 2xx-Status antworten, idealerweise innerhalb weniger Sekunden. Wenn die Verarbeitung länger dauert, stellen Sie das Ereignis in eine Warteschlange für die Hintergrundverarbeitung. Dies verhindert Timeouts und ermöglicht es dem Absender, die Zustellung als erfolgreich zu betrachten.

2. Exponentielles Backoff mit Jitter implementieren

Wenn eine Zustellung fehlschlägt (Nicht-2xx-Antwort oder Timeout), sollte der Absender mit zunehmenden Verzögerungen erneut versuchen. Exponentielles Backoff (z. B. 1s, 2s, 4s, 8s...) verhindert, dass Ihr Endpunkt überlastet wird. Das Hinzufügen von zufälligem Jitter vermeidet Thundering-Herd-Probleme, wenn viele Webhooks gleichzeitig fehlschlagen.

Beispiel für einen Retry-Zeitplan:

• Versuch 1: sofort
• Versuch 2: nach 30 Sekunden
• Versuch 3: nach 2 Minuten
• Versuch 4: nach 10 Minuten
• Versuch 5: nach 1 Stunde

Nach einer maximalen Anzahl von Wiederholungen (z. B. 5) sollte der Absender aufhören und Sie benachrichtigen (z. B. per E-Mail oder Dashboard).

3. Duplikate mit Idempotenz behandeln

Wiederholungen können zu doppelten Zustellungen führen. Ihr Endpunkt muss idempotent sein: Die mehrfache Verarbeitung desselben Ereignisses sollte dieselbe Wirkung haben wie die einmalige Verarbeitung. Verwenden Sie eine eindeutige Ereignis-ID aus der Payload und speichern Sie diese. Überprüfen Sie vor der Verarbeitung, ob die ID bereits gesehen wurde; wenn ja, geben Sie 200 zurück, ohne erneut zu verarbeiten.

Gängige Ansätze:

• Eindeutige Datenbankeinschränkung für die Ereignis-ID.
• Redis-Set mit TTL für kürzlich verarbeitete IDs.
• Idempotenzschlüssel in Ihrer Geschäftslogik.

Vergleich: Signierte Payloads vs. andere Sicherheitsmaßnahmen

HMAC-Signaturen sind der De-facto-Standard, da sie zustandslos, effizient und bei korrekter Implementierung sehr sicher sind.

Best Practices für Webhook-Konsumenten

• Validieren Sie Signaturen bei jeder Anfrage, auch in der Entwicklung.
• Antworten Sie schnell; lagern Sie schwere Verarbeitung in eine Warteschlange aus.
• Protokollieren Sie alles – Header, Payload und Verarbeitungsergebnis – zum Debuggen.
• Überwachen Sie Fehler und richten Sie Warnungen für wiederholte Fehler ein.
• Verwenden Sie HTTPS, um Payloads während der Übertragung zu schützen.
• Rotieren Sie Geheimnisse regelmäßig und unterstützen Sie mehrere aktive Geheimnisse während der Rotation.

Best Practices für Webhook-Produzenten

• Signieren Sie Payloads mit einem für jeden Konsumenten eindeutigen Geheimnis.
• Fügen Sie eine eindeutige Ereignis-ID hinzu, um die Idempotenz zu unterstützen.
• Wiederholen Sie mit Backoff und begrenzen Sie die Versuche.
• Stellen Sie ein Dashboard bereit, auf dem Konsumenten Zustellungsprotokolle einsehen und Ereignisse erneut abspielen können.
• Dokumentieren Sie Ihr Signaturschema klar und deutlich.

Testen Ihrer Webhook-Implementierung

Verwenden Sie Tools wie ngrok, um Ihren lokalen Server verfügbar zu machen und Webhook-Zustellungen zu simulieren. Schreiben Sie Unit-Tests für die Signaturverifizierung und die Idempotenzlogik. Für Lasttests ziehen Sie Tools in Betracht, die signierte Anfragen in großem Umfang senden können.

Beim Debuggen inspizieren Sie die rohe Payload und die Header. Ein JSON-Formatierer kann helfen, die Struktur der Payload zu visualisieren. Probieren Sie unseren JSON Formatter, um Webhook-Payloads schnell hübsch zu formatieren und zu validieren.

FAQ

Was ist eine signierte Webhook-Payload?

Eine signierte Payload enthält eine kryptografische Signatur (normalerweise HMAC), die es dem Empfänger ermöglicht, die Identität des Absenders zu überprüfen und sicherzustellen, dass die Payload nicht verändert wurde. Sie wird mit einem gemeinsamen Geheimnis und dem Request-Body berechnet.

Wie oft sollte ein Webhook wiederholt werden?

Es gibt keine universelle Zahl, aber üblich sind 3–5 Wiederholungen mit exponentiellem Backoff. Danach gilt das Ereignis als fehlgeschlagen und der Konsument sollte benachrichtigt werden, um zu untersuchen oder manuell erneut abzuspielen.

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

Ja, JWT kann funktionieren, fügt aber Komplexität hinzu (Token-Ausstellung, Ablauf). HMAC ist einfacher und für die meisten Anwendungsfälle ausreichend. Wählen Sie basierend auf Ihrer vorhandenen Infrastruktur und Ihren Anforderungen.

Bereit, Webhook-Payloads zu inspizieren und zu debuggen? Verwenden Sie unseren kostenlosen JSON Formatter, um JSON sofort zu formatieren und zu validieren.