Webhooks erklärt: Signierte Payloads und Retry-Strategien

Warum Webhooks fehlschlagen und wie Sie das beheben

Sie haben gerade den Webhook eines Zahlungsanbieters integriert, um Bestellstatus in Ihrer App zu aktualisieren. Im Test funktioniert alles, aber in der Produktion kommen einige Events nie an oder – schlimmer noch – Sie erhalten Duplikate. Ohne geeignete Schutzmaßnahmen können Webhooks zu einer Quelle stiller Fehler und Sicherheitslücken werden.

Webhooks sind HTTP-Callbacks, die durch Ereignisse ausgelöst werden. Anders als typische API-Aufrufe sind sie jedoch push-basiert und asynchron. Das bringt zwei zentrale Herausforderungen mit sich: die Authentizität zu überprüfen und die Zustellung sicherzustellen. In diesem Leitfaden gehen wir beide an – mit signierten Payloads und intelligenten Retries.

Was sind Webhooks?

Ein Webhook ist ein benutzerdefinierter HTTP-Callback. Wenn ein Ereignis in einem Quellsystem auftritt (z. B. eine neue Zahlung), sendet es eine HTTP-POST-Anfrage an eine von Ihnen bereitgestellte URL, die die Ereignisdaten enthält. Dies ermöglicht Echtzeitreaktionen ohne Polling.

Häufige Anwendungsfälle sind Zahlungsbenachrichtigungen, CI/CD-Trigger und Chat-Integrationen. Da Webhooks jedoch das öffentliche Internet durchqueren, sind sie anfällig für Spoofing und Verlust.

Webhooks mit signierten Payloads absichern

Woher wissen Sie, dass ein Webhook wirklich von Ihrem Anbieter stammt? Die Signierung der Nutzdaten mit einem gemeinsamen Geheimnis gewährleistet Integrität und Authentizität.

So funktionieren HMAC-Signaturen

Der Anbieter berechnet einen HMAC (z. B. SHA-256) des Request-Bodys mit einem geheimen Schlüssel und sendet die Signatur in einem Header (z. B. X-Signature). Ihr Server berechnet den HMAC neu und vergleicht ihn mit einem konstanten Zeitvergleich, um Timing-Angriffe zu verhindern.

// Node.js-Beispiel: Überprüfen einer Webhook-Signatur
const crypto = require('crypto');

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

Best Practices:

• Verwenden Sie ein starkes, eindeutiges Geheimnis pro Webhook-Endpunkt.
• Fügen Sie einen Zeitstempel in die signierten Nutzdaten ein, um Replay-Angriffe zu verhindern; lehnen Sie Anfragen ab, die älter als ein paar Minuten sind.
• Verwenden Sie immer HTTPS, um die Nutzdaten während der Übertragung zu schützen.

Zuverlässige Retries implementieren

Selbst mit Signaturen können Netzwerkprobleme oder Ausfälle dazu führen, dass die Webhook-Zustellung fehlschlägt. Anbieter versuchen es in der Regel mit exponentiellem Backoff erneut, aber auch Sie müssen auf Ihrer Seite Retries handhaben.

Idempotenz: Der Schlüssel für sichere Retries

Wiederholungen können zu doppelter Verarbeitung führen. Verwenden Sie Idempotenzschlüssel (oft in den Nutzdaten oder als Header enthalten), um sicherzustellen, dass jedes Ereignis genau einmal verarbeitet wird. Speichern Sie verarbeitete Ereignis-IDs und ignorieren Sie Duplikate.

// Beispiel: idempotenter Webhook-Handler
const processedEvents = new Set();

app.post('/webhook', (req, res) => {
  const eventId = req.body.id;
  if (processedEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  // Ereignis verarbeiten...
  processedEvents.add(eventId);
  res.status(200).send('OK');
});

Retry-Strategie auf der Empfängerseite

Wenn Ihre Verarbeitung fehlschlägt, antworten Sie mit einem 5xx-Status, um den Retry des Anbieters auszulösen. Bei vorübergehenden Fehlern können Sie auch eine eigene Retry-Warteschlange mit Backoff implementieren.

Überwachung und Debugging von Webhooks

Protokollieren Sie alle eingehenden Webhook-Anfragen mit Headern und Nutzdaten (sensibile Daten redigieren). Verwenden Sie ein Tool wie den JSON Formatter, um Nutzdaten für eine einfachere Überprüfung hübsch zu formatieren. Richten Sie Warnungen für fehlgeschlagene Zustellungen ein und verfolgen Sie die Anzahl der Wiederholungen.

FAQ

Was ist eine signierte Webhook-Nutzlast?

Eine signierte Nutzlast enthält eine kryptografische Signatur (normalerweise HMAC), die bestätigt, dass die Anfrage von einer vertrauenswürdigen Quelle stammt und nicht manipuliert wurde.

Wie oft sollte ich einen fehlgeschlagenen Webhook wiederholen?

Die meisten Anbieter wiederholen 3–5 Mal mit exponentiellem Backoff. Als Empfänger antworten Sie mit entsprechenden Statuscodes und überlassen die Wiederholungen dem Anbieter.

Kann ich Webhooks ohne HTTPS verwenden?

Nein – HTTPS ist unerlässlich, um die Nutzdaten zu verschlüsseln und Man-in-the-Middle-Angriffe zu verhindern. Akzeptieren Sie niemals Webhooks über einfaches HTTP.

Bereit, Webhook-Nutzdaten zu inspizieren und zu debuggen? Probieren Sie unseren kostenlosen JSON Formatter, um JSON-Daten sofort zu formatieren und zu validieren.