Webhooks erklärt: Signierte Payloads und Retries
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:
- Sicherheit: Woher wissen Sie, dass die Anfrage vom legitimen Absender stammt?
- Zuverlässigkeit: Was ist, wenn Ihr Endpunkt ausgefallen oder langsam ist?
- Duplikate: Netzwerke können Wiederholungen verursachen; Sie könnten dasselbe Ereignis mehrmals empfangen.
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:
- Anbieter und Verbraucher teilen einen geheimen Schlüssel.
- Der Anbieter erstellt die Nutzlast, berechnet HMAC-SHA256(secret, payload) und sendet sie in einem Header.
- 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
- Zeitstempelvalidierung: Fügen Sie einen Zeitstempel in die signierte Nutzlast ein und lehnen Sie alte Anfragen ab, um Replay-Angriffe zu verhindern.
- HTTPS: Verwenden Sie immer HTTPS für Webhook-Endpunkte.
- Geheimnisrotation: Unterstützen Sie mehrere aktive Geheimnisse, um eine Rotation ohne Ausfallzeiten zu ermöglichen.
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:
- Wiederholung 1: nach 1 Minute
- Wiederholung 2: nach 5 Minuten
- Wiederholung 3: nach 30 Minuten
- Wiederholung 4: nach 2 Stunden
- Wiederholung 5: nach 24 Stunden
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:
- Schnell antworten: Bestätigen Sie den Empfang mit einem 2xx-Status, bevor Sie schwere Arbeit verrichten. Verwenden Sie eine Warteschlange.
- Idempotenz: Behandeln Sie doppelte Ereignisse elegant. Verwenden Sie die Ereignis-ID zur Deduplizierung.
- Fehler überwachen: Protokollieren Sie Fehler und richten Sie Warnungen ein.
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:
- Speichern Sie verarbeitete Ereignis-IDs in einer Datenbank mit einer eindeutigen Einschränkung.
- Prüfen Sie vor der Verarbeitung, ob die ID bereits existiert; wenn ja, geben Sie 200 OK zurück, ohne erneut zu verarbeiten.
- Verwenden Sie für zustandsändernde Operationen Idempotenzschlüssel.
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.