Webhooks erklärt: Signierte Payloads und Retries
Du hast gerade einen Zahlungsanbieter oder einen CI/CD-Dienst integriert und musst nun Echtzeit-Events empfangen. Webhooks sind der Standardweg, um Daten zwischen Systemen zu übertragen, aber viele Implementierungen scheitern in der Produktion an Sicherheitslücken oder unzuverlässiger Zustellung. Dieser Leitfaden erklärt, wie du Webhooks mit signierten Payloads absicherst und robuste Retry-Mechanismen implementierst.
Was sind Webhooks und warum sie wichtig sind
Ein Webhook ist ein HTTP-Callback: Wenn in einem Quellsystem ein Event auftritt (z. B. eine neue Bestellung), sendet es eine HTTP-POST-Anfrage an eine URL, die du bereitstellst. Anders als Polling sind Webhooks effizient und nahezu in Echtzeit. Da sie jedoch auf HTTP basieren, musst du Sicherheit und Zuverlässigkeit explizit behandeln.
Typische Anwendungsfälle sind Zahlungsbenachrichtigungen, CI/CD-Pipeline-Trigger, Chat-Benachrichtigungen und die Synchronisierung von Daten zwischen SaaS-Anwendungen.
Webhooks mit signierten Payloads absichern
Webhooks sind öffentlich zugängliche Endpunkte, daher können Angreifer gefälschte Anfragen senden. Um dies zu verhindern, signieren Anbieter jeden Payload mit einem geheimen Schlüssel. Der Empfänger verifiziert die Signatur, um Authentizität und Integrität sicherzustellen.
Wie HMAC-Signaturen funktionieren
Die gängigste Methode ist HMAC-SHA256. Der Anbieter berechnet einen Hash des Request-Bodys mit einem gemeinsamen Secret und fügt ihn in einen Header ein (z. B. X-Signature). Der Empfänger berechnet den Hash neu und vergleicht ihn.
// Node.js-Beispiel: Signatur generieren
const crypto = require('crypto');
const secret = 'your_webhook_secret';
const payload = JSON.stringify({ event: 'order.created', id: 123 });
const signature = crypto.createHmac('sha256', secret).update(payload).digest('hex');
// Signatur im Header senden: X-Signature: sha256=...
Signaturen beim Empfänger verifizieren
Verwende immer einen Vergleich mit konstanter Laufzeit, um Timing-Angriffe zu verhindern. In Node.js nutzt du dafür crypto.timingSafeEqual.
// Express.js-Middleware-Beispiel
const crypto = require('crypto');
function verifySignature(req, res, next) {
const signature = req.headers['x-signature'];
const payload = JSON.stringify(req.body); // raw body needed
const expected = crypto.createHmac('sha256', secret).update(payload).digest('hex');
const trusted = Buffer.from(`sha256=${expected}`, 'utf8');
const received = Buffer.from(signature, 'utf8');
if (trusted.length !== received.length || !crypto.timingSafeEqual(trusted, received)) {
return res.status(401).send('Invalid signature');
}
next();
}
Wichtig: Verwende für die Verifizierung den rohen Request-Body, nicht das geparste JSON, um Abweichungen zu vermeiden.
Zusätzliche Sicherheitsmaßnahmen
- Timestamp-Validierung: Binde einen Zeitstempel in die Signatur ein und lehne Anfragen ab, die älter als einige Minuten sind, um Replay-Angriffe zu verhindern.
- Nur HTTPS: Verwende immer HTTPS-Endpunkte, um Daten während der Übertragung zu schützen.
- IP-Allowlisting: Wenn der Anbieter IP-Bereiche veröffentlicht, beschränke eingehende Anfragen auf diese IPs.
Zuverlässige Retries implementieren
Webhooks können aufgrund von Netzwerkproblemen, Serverausfällen oder Bugs fehlschlagen. Anbieter wiederholen fehlgeschlagene Zustellungen typischerweise mit exponentiellem Backoff. Als Empfänger musst du idempotent sein und doppelte Events verarbeiten können.
Idempotenz by Design
Jedes Webhook-Event sollte eine eindeutige ID haben. Speichere verarbeitete IDs, um Duplikate zu ignorieren. Verwende eine Datenbank mit Unique-Constraint oder einen Cache wie Redis.
// Pseudocode für idempotente Verarbeitung
if (await redis.exists(`webhook:${event.id}`)) {
return res.status(200).send('Already processed');
}
await processEvent(event);
await redis.set(`webhook:${event.id}`, '1', 'EX', 86400); // 24h TTL
Retry-Strategien
Anbieter wiederholen in der Regel mit zunehmenden Verzögerungen (z. B. 1s, 5s, 30s, 5m, 1h). Stelle sicher, dass dein Endpunkt schnell antwortet (innerhalb von 5 Sekunden), um Timeouts zu vermeiden. Wenn die Verarbeitung länger dauert, bestätige den Empfang und verarbeite asynchron.
Hier ein Vergleich gängiger Retry-Muster:
| Muster | Vorteile | Nachteile |
|---|---|---|
| Festes Intervall | Einfach | Kann einen sich erholenden Server überlasten |
| Exponentielles Backoff | Reduziert die Last während Ausfällen | Verzögerte Zustellung bei temporären Fehlern |
| Exponentielles Backoff mit Jitter | Verhindert Thundering Herd | Etwas komplexer |
Monitoring und Dead Letter Queues
Logge alle Webhook-Versuche und -Fehler. Nach einer maximalen Anzahl von Retries verschiebe Events in eine Dead Letter Queue (DLQ) zur manuellen Prüfung. Löse Alarme bei hohen Fehlerraten aus.
Alles zusammenführen: Eine Schritt-für-Schritt-Implementierung
- Richte einen HTTPS-Endpunkt ein, der POST-Anfragen akzeptiert und den rohen Body liest.
- Verifiziere die Signatur mit dem gemeinsamen Secret und einem Vergleich mit konstanter Laufzeit.
- Prüfe den Zeitstempel, um Replay-Angriffe zu verhindern (falls vorhanden).
- Stelle Idempotenz sicher, indem du die Event-ID gegen einen Cache oder eine Datenbank prüfst.
- Verarbeite das Event asynchron, wenn es Zeit in Anspruch nehmen könnte; antworte sofort mit 200 OK.
- Implementiere Retry-Logik auf der Senderseite mit exponentiellem Backoff und Jitter.
- Überwache und alarmiere bei Fehlern und nutze eine DLQ für persistente Fehler.
FAQ
Was ist ein signierter Webhook-Payload?
Ein signierter Payload enthält eine kryptografische Signatur (meist HMAC), mit der der Empfänger verifizieren kann, dass die Anfrage von einer vertrauenswürdigen Quelle stammt und nicht manipuliert wurde.
Wie gehe ich mit doppelten Webhook-Events um?
Verwende die im Payload bereitgestellte eindeutige Event-ID, um verarbeitete Events zu verfolgen. Speichere IDs in einer Datenbank oder einem Cache mit TTL, um Duplikate zu ignorieren.
Was sollte mein Webhook-Endpunkt zurückgeben?
Gib schnell einen 2xx-Statuscode zurück (z. B. 200 OK), um den Empfang zu bestätigen. Wenn die Verarbeitung fehlschlägt, gib einen 5xx zurück, um einen Retry auszulösen – aber nur bei temporären Fehlern.
Beim Testen von Webhook-Payloads musst du möglicherweise JSON-Strukturen inspizieren. Nutze den JSON Formatter, um Webhook-Payloads zu validieren und hübsch zu formatieren, damit das Debugging einfacher wird.