Webhooks erklärt: Signierte Payloads und zuverlässige Wiederholungen

Backend2026-11-17TryQuickToolBox

Sie haben gerade einen Drittanbieterdienst integriert, der Webhooks an Ihren Endpunkt sendet. In Tests funktioniert alles, aber in der Produktion stellen Sie fest, dass Ereignisse fehlen, Zustellungen dupliziert werden und sogar gefälschte Anfragen eintreffen. Webhooks sind im Konzept einfach, aber schwierig richtig umzusetzen. Dieser Artikel erklärt, wie Sie Webhooks mit signierten Payloads absichern und zuverlässige Wiederholungslogik implementieren, damit Ihre Integrationen robust und vertrauenswürdig sind.

Was sind Webhooks und warum sie wichtig sind

Webhooks sind benutzerdefinierte HTTP-Callbacks, die durch Ereignisse ausgelöst werden. Anstatt eine API auf Änderungen zu pollen, registrieren Sie eine URL, und der Dienst sendet eine POST-Anfrage mit Ereignisdaten, sobald etwas passiert. Dieses Push-Modell reduziert Latenz und Serverlast und ist ideal für Echtzeit-Integrationen wie Zahlungsbenachrichtigungen, CI/CD-Trigger und Chat-Nachrichten.

Webhooks bringen jedoch Herausforderungen mit sich: die Authentizität zu überprüfen, Fehler zu behandeln und eine Exactly-Once-Verarbeitung sicherzustellen. Lassen Sie uns diese nacheinander angehen.

Webhooks mit signierten Payloads absichern

Ohne Verifikation kann jeder gefälschte Anfragen an Ihren Webhook-Endpunkt senden. Signierte Payloads lösen dies, indem sie eine kryptografische Signatur in den Anfrage-Headern enthalten, die mit einem gemeinsamen Geheimnis generiert wird. Sie verifizieren die Signatur, um zu bestätigen, dass die Anfrage vom erwarteten Absender stammt und nicht manipuliert wurde.

Wie HMAC-Signaturen funktionieren

Die meisten Dienste verwenden HMAC (Hash-based Message Authentication Code) mit SHA-256. Der Absender berechnet einen Hash des Anfrage-Bodys (und manchmal eines Zeitstempels) mit dem Geheimnis und fügt ihn in einen Header wie X-Signature ein. Sie berechnen den Hash auf Ihrer Seite neu und vergleichen.

Hier ist ein typischer Verifikationsablauf in Node.js:

const crypto = require('crypto');

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

Verwenden Sie immer einen zeitkonstanten Vergleich, um Timing-Angriffe zu verhindern. Fügen Sie außerdem einen Zeitstempel in die signierten Daten ein und lehnen Sie Anfragen ab, die älter als ein paar Minuten sind, um Replay-Angriffe zu verhindern.

Best Practices für die Signaturverifikation

Zuverlässige Wiederholungen implementieren

Netzwerke fallen aus, Server starten neu und Endpunkte laufen in Timeouts. Ein robustes Webhook-System muss fehlgeschlagene Zustellungen wiederholen. Aber Wiederholungen können Duplikate verursachen, daher benötigen Sie Idempotenz.

Wiederholungsstrategien

Die meisten 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 (z. B. 5). Fügen Sie eine eindeutige Ereignis-ID in die Payload ein, damit der Empfänger deduplizieren kann.

Auf der Empfängerseite antworten Sie schnell mit einem 2xx-Status, um den Empfang zu bestätigen, und verarbeiten dann asynchron. Wenn die Verarbeitung fehlschlägt, können Sie sich nicht darauf verlassen, dass der Absender unbegrenzt wiederholt – implementieren Sie Ihre eigene Dead-Letter-Queue oder Alarmierung.

Idempotenzschlüssel

Um doppelte Zustellungen zu behandeln, verwenden Sie einen Idempotenzschlüssel (oft die Ereignis-ID) und speichern Sie verarbeitete IDs für einen angemessenen Zeitraum. Prüfen Sie vor der Verarbeitung, ob die ID bereits gesehen wurde; wenn ja, geben Sie Erfolg zurück, ohne erneut zu verarbeiten.

// Beispiel: Idempotenzprüfung in Express
app.post('/webhook', async (req, res) => {
  const eventId = req.body.id;
  if (await db.seenEvents.has(eventId)) {
    return res.status(200).send('Already processed');
  }
  await db.seenEvents.add(eventId);
  // Ereignis asynchron verarbeiten
  res.status(200).send('OK');
});

Vergleich: Polling vs. Webhooks

AspektPollingWebhooks
LatenzHoch (intervallbasiert)Niedrig (nahezu Echtzeit)
ServerlastHoch (häufige Anfragen)Niedrig (ereignisgesteuert)
KomplexitätEinfach zu implementierenErfordert Signaturverifikation und Wiederholungen
ZuverlässigkeitAbhängig von der Polling-FrequenzAbhängig vom Wiederholungsmechanismus

Schritt für Schritt: Einen sicheren Webhook-Empfänger bauen

  1. Richten Sie einen Endpunkt ein, der POST-Anfragen über HTTPS akzeptiert.
  2. Verifizieren Sie die Signatur mit dem gemeinsamen Geheimnis und lehnen Sie ungültige Anfragen mit 401 ab.
  3. Prüfen Sie den Zeitstempel, um Replay-Angriffe zu verhindern.
  4. Antworten Sie sofort mit 200 OK nach der Basisvalidierung und verarbeiten Sie dann asynchron.
  5. Implementieren Sie Idempotenz mit Ereignis-IDs, um doppelte Verarbeitung zu vermeiden.
  6. Protokollieren und überwachen Sie Fehler und Wiederholungen.

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 Authentizität und Integrität der Anfrage mit einem gemeinsamen Geheimnis zu überprüfen.

Wie oft sollte ich einen fehlgeschlagenen Webhook wiederholen?

Übliche Praxis sind 3–5 Wiederholungen mit exponentiellem Backoff. Danach verschieben Sie das Ereignis in eine Dead-Letter-Queue zur manuellen Überprüfung.

Kann ich Webhooks ohne HTTPS verwenden?

Nein, HTTPS ist unerlässlich, um die Payload und Signatur vor Abhören und Manipulation zu schützen. Verwenden Sie immer TLS.

Bereit, Ihre Webhook-Payloads zu testen? Verwenden Sie unseren JSON-Formatter, um JSON-Payloads schnell zu verschönern und zu validieren.