Webhooks erklärt: Signierte Payloads und Retries

Sie haben gerade ein Zahlungsgateway integriert. Die Dokumentation sagt: „Wir senden eine POST-Anfrage an Ihren Endpunkt, wenn eine Zahlung erfolgreich ist.“ Einfach, oder? Sie bauen eine einfache Route, die JSON akzeptiert, Ihre Datenbank aktualisiert und 200 zurückgibt. Dann passiert es: Die Zahlung eines Kunden ist erfolgreich, aber Ihr Server ist kurzzeitig nicht erreichbar. Der Webhook kommt nie an. Oder schlimmer: Er kommt zweimal an, und Sie schreiben dem Konto doppelt gut. Webhooks scheinen einfach zu sein, bis sie fehlschlagen.

Dieser Artikel erklärt, wie Webhooks wirklich funktionieren, warum signierte Payloads für die Sicherheit unerlässlich sind und wie Sie eine Retry-Logik aufbauen, die Ihre Integration zuverlässig hält – auch wenn etwas schiefgeht.

Was ist ein Webhook?

Ein Webhook ist ein HTTP-Callback: Statt dass Ihre Anwendung eine API auf Änderungen pollt, sendet der Anbieter eine HTTP-POST-Anfrage an eine von Ihnen angegebene URL, wenn ein Ereignis eintritt. Es ist Push statt Pull.

Häufige Beispiele sind Zahlungsbestätigungen (Stripe, PayPal), CI/CD-Build-Benachrichtigungen (GitHub, GitLab) und Messaging-Plattformen (Slack, Discord). Das Muster ist einfach: Sie registrieren eine URL, der Anbieter sendet JSON-Payloads an diese URL, und Ihr Server verarbeitet sie.

Aber diese Einfachheit verbirgt zwei kritische Herausforderungen: Authentizität (Woher wissen Sie, dass die Anfrage wirklich vom Anbieter kommt?) und Zuverlässigkeit (Was passiert, wenn Ihr Endpunkt nicht erreichbar oder langsam ist?).

Warum signierte Payloads wichtig sind

Ihr Webhook-Endpunkt ist eine öffentliche URL. Jeder kann eine POST-Anfrage daran senden. Ohne Verifizierung könnte ein Angreifer ein Zahlungserfolgsereignis fälschen, einen Versand auslösen oder Ihre Daten beschädigen.

Signierte Payloads lösen dies, indem sie eine kryptografische Signatur in die Anfrage-Header aufnehmen. Der Anbieter berechnet einen HMAC (hashbasierter Nachrichtenauthentifizierungscode) unter Verwendung eines gemeinsamen Geheimnisses und des Anfrage-Bodys und sendet ihn zusammen mit dem Payload. Ihr Server berechnet den HMAC neu und vergleicht ihn. Wenn sie übereinstimmen, ist die Anfrage authentisch.

Wie HMAC-Signierung funktioniert

1. Der Anbieter und Sie teilen einen geheimen Schlüssel (bei der Einrichtung bereitgestellt).
2. Für jeden Webhook verkettet der Anbieter den Zeitstempel und den rohen Anfrage-Body und berechnet dann einen HMAC-SHA256-Hash mit dem Geheimnis.
3. Die Signatur wird in einem Header gesendet, oft etwas wie X-Signature oder Stripe-Signature.
4. Ihr Server berechnet den HMAC mit demselben Geheimnis neu und vergleicht ihn mit der empfangenen Signatur.
5. Wenn sie übereinstimmen, verarbeiten Sie das Ereignis; andernfalls lehnen Sie es mit 401 ab.

Verwenden Sie immer den rohen Anfrage-Body für die HMAC-Berechnung. Wenn Ihr Framework JSON parst, bevor Sie verifizieren, kann der Body verändert werden (Leerzeichen, Schlüsselreihenfolge), was die Verifizierung fehlschlagen lässt.

Beispiel: Verifizierung einer Webhook-Signatur in Node.js

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

// Use raw body for signature verification
app.post('/webhook', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-signature'];
  const secret = process.env.WEBHOOK_SECRET;
  const payload = req.body; // Buffer

  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    return res.status(401).send('Invalid signature');
  }

  // Process the event
  const event = JSON.parse(payload.toString());
  // ... handle event

  res.status(200).send('OK');
});

Beachten Sie die Verwendung von timingSafeEqual, um Timing-Angriffe zu verhindern. Verwenden Sie niemals einen einfachen ===-Vergleich für Signaturen.

Retry-Logik entwerfen

Auch mit Signaturen können Webhooks fehlschlagen. Ihr Server könnte nicht erreichbar sein, das Netzwerk könnte die Anfrage verlieren oder Ihre Verarbeitung könnte in einen Timeout laufen. Anbieter wiederholen fehlgeschlagene Zustellungen in der Regel, aber Sie sollten Ihr System auch so gestalten, dass es Retries elegant verarbeitet.

Was gilt als Fehler?

Die meisten Anbieter betrachten jede Antwort außer 2xx als Fehler. Dazu gehören 3xx-Weiterleitungen, 4xx-Client-Fehler und 5xx-Server-Fehler. Einige erzwingen auch ein Timeout (z. B. 5 Sekunden). Wenn Sie nicht schnell antworten, wird die Zustellung als fehlgeschlagen markiert und wiederholt.

Exponentielles Backoff mit Jitter

Anbieter wiederholen normalerweise mit exponentiellem Backoff: erste Wiederholung nach 1 Minute, dann 5 Minuten, 30 Minuten usw. Das Hinzufügen von Jitter (zufällige Variation) verhindert Thundering Herds, wenn viele Webhooks gleichzeitig fehlschlagen.

Wenn Sie einen Webhook-Sender bauen, implementieren Sie Backoff wie folgt:

• Wiederholung 1: nach 10 Sekunden
• Wiederholung 2: nach 1 Minute
• Wiederholung 3: nach 5 Minuten
• Wiederholung 4: nach 30 Minuten
• Wiederholung 5: nach 2 Stunden

Nach einer maximalen Anzahl von Versuchen verschieben Sie das Ereignis in eine Dead-Letter-Queue zur manuellen Überprüfung.

Idempotenz: Umgang mit doppelten Zustellungen

Wiederholungen bedeuten, dass Ihr Endpunkt dasselbe Ereignis mehrmals empfangen kann. Ihre Verarbeitung muss idempotent sein: Die zweimalige Verarbeitung desselben Ereignisses sollte denselben Effekt haben wie die einmalige Verarbeitung.

Häufige Strategien:

• Event-ID-Deduplizierung: Speichern Sie verarbeitete Event-IDs in einer Datenbank oder einem Cache. Prüfen Sie vor der Verarbeitung, ob die ID bereits gesehen wurde.
• Upsert statt Insert: Verwenden Sie Datenbankoperationen, die Duplikate natürlich behandeln (z. B. INSERT ... ON CONFLICT DO NOTHING).
• Idempotenzschlüssel: Übergeben Sie für Operationen wie das Belasten einer Karte einen eindeutigen Schlüssel, damit der Zahlungsanbieter doppelte Anfragen ignoriert.

Best Practices für Webhook-Konsumenten

Erwägen Sie auch, den Zeitstempel in der Signatur zu validieren, um Replay-Angriffe zu verhindern. Viele Anbieter fügen einen Zeitstempel in das signierte Payload ein; lehnen Sie Ereignisse ab, die älter als ein paar Minuten sind.

Best Practices für Webhook-Produzenten

Wenn Sie einen Dienst bauen, der Webhooks sendet, befolgen Sie diese Richtlinien:

• Signieren Sie jedes Payload mit HMAC-SHA256.
• Fügen Sie eine eindeutige Event-ID und einen Zeitstempel ein.
• Wiederholen Sie mit exponentiellem Backoff und Jitter.
• Bieten Sie Konsumenten eine Möglichkeit, Zustellungsprotokolle einzusehen und Ereignisse manuell erneut abzuspielen.
• Dokumentieren Sie Ihren Signaturverifizierungsprozess klar.

FAQ

Was ist ein signiertes Webhook-Payload?

Ein signiertes Payload enthält eine kryptografische Signatur (normalerweise HMAC), die aus dem Anfrage-Body und einem gemeinsamen Geheimnis berechnet wird. Der Empfänger verifiziert die Signatur, um sicherzustellen, dass die Anfrage authentisch und unverändert ist.

Wie oft sollte ein Webhook wiederholt werden?

Es gibt keine universelle Zahl, aber die meisten Anbieter wiederholen 3–5 Mal über mehrere Stunden. Danach wird das Ereignis in der Regel als fehlgeschlagen markiert und kann für manuelles Replay verfügbar sein. Ihr System sollte Duplikate unabhängig von der Wiederholungsanzahl idempotent behandeln.

Kann ich Webhooks ohne HTTPS verwenden?

Technisch ja, aber Sie sollten immer HTTPS verwenden. Webhooks enthalten oft sensible Daten, und ohne TLS könnte ein Angreifer das Payload abfangen oder manipulieren. HTTPS stellt auch sicher, dass Sie an den vorgesehenen Server senden.

Debugging von Webhooks mit Nginx-Logs

Wenn Webhooks fehlschlagen, ist die erste Anlaufstelle Ihr Webserver-Log. Wenn Sie Nginx verwenden, zeichnen das Access- und Error-Log jede Anfrage auf, einschließlich Statuscodes und Antwortzeiten. Sie können schnell Muster erkennen: wiederholte 401s (Signaturverifizierung schlägt fehl), 500s (Anwendungsfehler) oder Timeouts.

Für eine schnellere Analyse versuchen Sie den Nginx Log Analyzer, um Webhook-Traffic zu parsen und zusammenzufassen, nach Statuscode zu filtern und problematische Endpunkte zu identifizieren.