Webhooks erklärt: Signierte Payloads und Retries

Backend2026-11-15TryQuickToolBox

Warum Webhooks in der Produktion versagen

Sie haben einen Webhook-Endpunkt erstellt, ihn lokal getestet und alles funktioniert. Dann schlägt die Produktion zu: Ein Anbieter sendet ein doppeltes Ereignis, Ihr Endpunkt läuft in eine Zeitüberschreitung oder ein Angreifer fälscht eine Anfrage. Plötzlich ist Ihre Integration unzuverlässig und unsicher.

Webhooks sind im Konzept einfach – HTTP-Callbacks, die durch Ereignisse ausgelöst werden –, aber produktionsreife Implementierungen erfordern eine sorgfältige Handhabung von Sicherheit und Zuverlässigkeit. Dieser Leitfaden behandelt zwei kritische Aspekte: signierte Payloads zur Überprüfung der Authentizität und Wiederholungsstrategien zur Behandlung von Fehlern.

Was sind Webhooks?

Ein Webhook ist ein benutzerdefinierter HTTP-Callback. Wenn ein Ereignis in einem Quellsystem auftritt (z. B. eine Zahlung ist erfolgreich), sendet es eine HTTP-POST-Anfrage an eine von Ihnen bereitgestellte URL, die Daten über das Ereignis enthält. Dieses Push-Modell ist effizienter als Polling.

Aber Webhooks bringen Herausforderungen mit sich:

Kümmern wir uns zuerst um die Sicherheit.

Webhooks mit signierten Payloads absichern

Signierte Payloads verwenden ein gemeinsames Geheimnis, um eine kryptografische Signatur des Anfragetexts zu erstellen. Der Absender fügt diese Signatur in einen Header ein (z. B. X-Signature). Ihr Endpunkt berechnet die Signatur neu und vergleicht sie. Wenn sie übereinstimmen, ist die Anfrage authentisch.

Wie HMAC-Signierung funktioniert

Die meisten Anbieter verwenden HMAC-SHA256. Die Signatur wird über den rohen Anfragetext unter Verwendung des gemeinsamen Geheimnisses berechnet. Hier ist der Ablauf:

  1. Anbieter und Verbraucher teilen einen geheimen Schlüssel.
  2. Der Anbieter erstellt die Nutzlast, berechnet HMAC-SHA256(secret, payload) und sendet sie in einem Header.
  3. Der Verbraucher empfängt die Anfrage, liest den rohen Text, berechnet denselben HMAC und vergleicht.

Wichtig: Verwenden Sie den rohen Text genau so, wie er empfangen wurde – das Parsen und erneute Serialisieren von JSON kann die Bytes verändern und die Signatur brechen.

Implementierung der Signaturprüfung

Hier ist ein Node.js-Beispiel mit Express:

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

// Use raw body parser for webhook routes
app.post('/webhook', express.raw({ type: 'application/json' }), (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');
  }
  
  // Process the event
  const event = JSON.parse(req.body);
  // ... handle event
  
  res.status(200).send('OK');
});

Verwenden Sie immer einen Vergleich mit konstanter Zeit wie crypto.timingSafeEqual, um Timing-Angriffe zu verhindern.

Weitere Sicherheitsüberlegungen

Zuverlässige Wiederholungsversuche implementieren

Selbst mit einem sicheren Endpunkt können Netzwerkprobleme oder vorübergehende Fehler dazu führen, dass die Webhook-Zustellung fehlschlägt. Ein robuster Wiederholungsmechanismus stellt sicher, dass Ereignisse nicht verloren gehen.

Wiederholungsstrategie auf der Senderseite

Wenn Sie einen Webhook-Sender erstellen, implementieren Sie exponentielles Backoff mit Jitter. Zum Beispiel:

Fügen Sie zufälligen Jitter hinzu, um Thundering-Herd-Probleme zu vermeiden. Hören Sie nach einer maximalen Anzahl von Versuchen auf und alarmieren Sie.

Best Practices auf der Empfängerseite

Als Webhook-Verbraucher können Sie die Wiederholungsrichtlinie des Senders nicht steuern, aber Sie können Ihren Endpunkt widerstandsfähig machen:

Umgang mit Duplikaten durch Idempotenz

Webhook-Anbieter wiederholen oft bei Zeitüberschreitungen, sodass Sie dasselbe Ereignis mehrmals empfangen können. Machen Sie Ihre Verarbeitung idempotent:

Beispiel mit einem eindeutigen Datenbankindex:

async function handleEvent(event) {
  try {
    await db.query('INSERT INTO processed_events (id) VALUES ($1)', [event.id]);
  } catch (err) {
    if (err.code === '23505') { // unique violation
      return; // already processed
    }
    throw err;
  }
  // process event
}

Vergleich: Ansätze für Webhook-Sicherheit

Ansatz Vorteile Nachteile
HMAC-Signatur Starke Integrität, weit verbreitet Erfordert Geheimnisverwaltung
Basic Auth Einfach Weniger sicher, Anmeldeinformationen im Header
IP-Allowlist Einfach zu implementieren IPs können sich ändern, nicht robust

HMAC-Signaturen sind der De-facto-Standard für Webhook-Sicherheit.

Webhooks lokal testen

Tools wie ngrok oder localtunnel machen Ihren lokalen Server für Tests über das Internet erreichbar. Testen Sie immer die Signaturprüfung und die Wiederholungslogik mit simulierten Fehlern.

Bei der Untersuchung von JSON-Payloads von Webhooks kann die Formatierung beim Debuggen helfen. Probieren Sie unseren JSON Formatter, um Webhook-Payloads übersichtlich zu formatieren und zu validieren.

FAQ

Wie überprüfe ich eine Webhook-Signatur?

Berechnen Sie einen HMAC des rohen Anfragetexts mit dem gemeinsamen Geheimnis und vergleichen Sie ihn dann mit dem Signatur-Header unter Verwendung einer Vergleichsfunktion mit konstanter Zeit.

Was soll ich tun, wenn mein Webhook-Endpunkt ausgefallen ist?

Die meisten Anbieter wiederholen mit exponentiellem Backoff. Stellen Sie sicher, dass Ihr Endpunkt schnell einen 2xx-Status zurückgibt und asynchron verarbeitet, um die Auswirkungen von Ausfallzeiten zu minimieren.

Kann ich Webhooks ohne Signaturen verwenden?

Das ist riskant. Ohne Signaturen können Angreifer Anfragen fälschen. Verwenden Sie immer signierte Payloads oder zumindest Basisauthentifizierung über HTTPS.

Fazit

Webhooks sind leistungsstark, erfordern aber Aufmerksamkeit für Sicherheit und Zuverlässigkeit. Implementieren Sie die HMAC-Signaturprüfung, um die Authentizität sicherzustellen, und entwerfen Sie Ihr System so, dass es Wiederholungen und Duplikate elegant verarbeitet. Mit diesen Praktiken werden Ihre Webhook-Integrationen robust und produktionsbereit.