Webhooks erklärt: Signierte Payloads und Retries

Sie haben gerade ein Zahlungsgateway oder einen CI/CD-Dienst integriert und müssen nun Echtzeit-Events empfangen. Webhooks sind die Standardlösung, aber sie bergen Fallstricke: nicht authentifizierte Payloads, verlorene Events und doppelte Zustellungen. Dieser Artikel erklärt, wie Webhooks funktionieren, wie Sie Payloads signieren, um Manipulation zu verhindern, und wie Sie Retries für eine zuverlässige Zustellung implementieren.

Was sind Webhooks?

Ein Webhook ist ein benutzerdefinierter HTTP-Callback. Anstatt dass Ihre Anwendung eine API nach Updates abfragt, sendet der Anbieter eine HTTP-POST-Anfrage an eine von Ihnen angegebene URL, sobald ein Event auftritt. Dies ist effizienter und ermöglicht nahezu Echtzeit-Reaktionen.

Häufige Anwendungsfälle sind:

• Zahlungsbenachrichtigungen (z. B. Stripe, PayPal)
• CI/CD-Build-Status (z. B. GitHub, GitLab)
• Messaging-Plattformen (z. B. Slack, Discord)
• CRM-Updates (z. B. Salesforce)

Warum sollten Webhook-Payloads signiert werden?

Webhook-Endpunkte sind öffentlich zugängliche URLs. Ohne Verifizierung kann jeder gefälschte Payloads senden, was zu Datenverfälschung oder Sicherheitsverletzungen führen kann. Das Signieren von Payloads mit einem gemeinsamen Secret gewährleistet Authentizität und Integrität.

Die meisten Anbieter verwenden HMAC (Hash-based Message Authentication Code) mit SHA-256. Der Anbieter berechnet eine Signatur über den rohen Request-Body mit einem geheimen Schlüssel und fügt sie in einen Header ein (z. B. X-Hub-Signature-256). Ihr Server berechnet die Signatur neu und vergleicht sie.

So verifizieren Sie eine Signatur

Hier ist eine Schritt-für-Schritt-Anleitung:

1. Rufen Sie den rohen Body ab, genau wie er gesendet wurde. Analysieren oder verändern Sie ihn nicht vor der Verifizierung.
2. Extrahieren Sie die Signatur aus dem Header.
3. Berechnen Sie die erwartete Signatur mit HMAC-SHA256 und Ihrem Secret.
4. Vergleichen Sie mit einer zeitkonstanten Funktion, um Timing-Angriffe zu verhindern.

Beispiel in Node.js:

const crypto = require('crypto');

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

In Python:

import hmac
import hashlib

def verify_signature(payload, signature, secret):
    expected = hmac.new(secret.encode(), payload, hashlib.sha256).hexdigest()
    return hmac.compare_digest(f'sha256={expected}', signature)

Verwenden Sie immer einen zeitkonstanten Vergleich, um Informationslecks zu vermeiden.

Implementierung von Retries für Zuverlässigkeit

Netzwerke fallen aus, Server starten neu und Deployments finden statt. Ein robustes Webhook-System muss fehlgeschlagene Zustellungen wiederholen. Anbieter wiederholen in der Regel mit exponentiellem Backoff, aber Sie sollten auch auf Ihrer Empfängerseite Retries handhaben.

Retry-Strategien

• Exponentielles Backoff: Warten Sie 1s, 2s, 4s, 8s usw. zwischen den Wiederholungen.
• Maximale Versuche: Begrenzen Sie Wiederholungen, um Endlosschleifen zu vermeiden (z. B. 5 Versuche).
• Dead Letter Queue: Speichern Sie das Event nach maximalen Versuchen zur manuellen Überprüfung.
• Idempotenz: Stellen Sie sicher, dass die mehrfache Verarbeitung desselben Events keine doppelten Nebenwirkungen verursacht.

Idempotenzschlüssel

Viele Anbieter fügen eine eindeutige Event-ID hinzu (z. B. X-Event-ID). Speichern Sie verarbeitete IDs in einer Datenbank oder einem Cache, um Duplikate zu überspringen. Verwenden Sie beispielsweise Redis mit einer TTL, um gesehene IDs zu verfolgen.

Vergleich: Polling vs. Webhooks

Best Practices für Webhook-Consumer

• Schnell antworten: Geben Sie innerhalb weniger Sekunden 2xx zurück; verarbeiten Sie asynchron.
• Signaturen validieren: Überprüfen Sie immer vor der Verarbeitung.
• Alles loggen: Bewahren Sie rohe Payloads und Header zum Debuggen auf.
• HTTPS verwenden: Akzeptieren Sie niemals Webhooks über einfaches HTTP.
• Fehler überwachen: Richten Sie Alarme für wiederholte Retry-Fehler ein.

FAQ

Was ist eine Webhook-Signatur?

Eine Webhook-Signatur ist ein HMAC-Hash des Payloads, der mit einem gemeinsamen Secret erstellt wird. Sie ermöglicht dem Empfänger zu überprüfen, dass die Anfrage vom erwarteten Absender stammt und nicht manipuliert wurde.

Wie oft sollte ich einen fehlgeschlagenen Webhook wiederholen?

Es gibt keine universelle Zahl, aber 3–5 Wiederholungen mit exponentiellem Backoff sind üblich. Danach loggen Sie das Event in eine Dead Letter Queue zur manuellen Überprüfung.

Kann ich Webhooks ohne HTTPS verwenden?

Technisch ja, aber es ist höchst unsicher. Verwenden Sie immer HTTPS, um Payloads zu verschlüsseln und Man-in-the-Middle-Angriffe zu verhindern.

Bereit, Ihre Webhook-Endpunkte zu testen? Verwenden Sie unseren JSON Formatter, um Payloads schnell zu inspizieren und zu validieren.