Webhooks: Warum ein 200 noch keine zuverlässige Integration ist

Ein Webhook funktioniert im Test. Ein Event kommt an, der Handler schreibt einen Datensatz, antwortet mit 200 und alle sind zufrieden.

Das ist noch kein belastbarer Webhook.

Die eigentlichen Probleme beginnen oft erst dann, wenn ein Provider erneut zustellt, zwei Events in anderer Reihenfolge eintreffen, ein Request nach einem Timeout noch einmal gesendet wird oder jemand versucht, einen abgefangenen Request zu wiederholen. Dann zeigt sich, ob der Endpoint nur Daten entgegennimmt – oder ob er als verlässliche Integrationsgrenze gebaut wurde.

Stripe dokumentiert ausdrücklich, dass Events erneut zugestellt werden können, dass Live-Zustellungen über mehrere Tage wiederholt werden können und dass die Reihenfolge nicht garantiert ist. GitHub empfiehlt ebenfalls Signaturprüfung, eindeutige Delivery-IDs und eine schnelle 2xx-Antwort. Diese Eigenschaften sind keine exotischen Sonderfälle. Sie gehören zum Betriebsmodell von Webhooks.

Das gefährliche Missverständnis: Der Provider ruft doch nur unsere URL auf

Ein öffentlich erreichbarer Webhook-Endpoint ist zunächst genau das: eine öffentliche URL. Ohne zusätzliche Prüfung kann grundsätzlich jeder versuchen, Requests an diese URL zu senden. Deshalb darf Geschäftslogik nicht allein darauf vertrauen, dass ein Request wahrscheinlich vom erwarteten Dienst kommt.

Eine belastbare Verarbeitung trennt mindestens vier Fragen: Ist der Request authentisch und unverändert? Ist diese konkrete Zustellung noch frisch oder möglicherweise ein Replay? Haben wir dieses Event bereits verarbeitet? Kann die Verarbeitung wiederholt werden, ohne denselben Geschäftseffekt doppelt auszulösen?

Diese Fragen klingen ähnlich, lösen aber unterschiedliche Fehlerklassen.

Signaturprüfung schützt nur, wenn der tatsächlich signierte Body geprüft wird

Viele Webhook-Anbieter signieren den Request-Body mit einem geheimen Schlüssel. Stripe verwendet dafür HMAC mit SHA-256 und bezieht zusätzlich einen Zeitstempel in den signierten Inhalt ein. GitHub verwendet für X-Hub-Signature-256 ebenfalls HMAC-SHA256. HMAC selbst ist als Mechanismus zur Nachrichtenauthentifizierung in RFC 2104 beschrieben.

Der praktische Stolperstein liegt häufig nicht in der Kryptografie, sondern im Framework. Wenn Middleware den JSON-Body bereits geparst, normalisiert oder neu serialisiert hat, kann sich die Bytefolge gegenüber dem ursprünglich signierten Request verändern. Stripe weist deshalb ausdrücklich darauf hin, dass für die Signaturprüfung der unveränderte Raw Body benötigt wird.

Ein Review sollte daher nicht nur fragen, ob irgendwo eine Funktion namens verifySignature() existiert. Entscheidend ist, welche Bytes tatsächlich verifiziert werden, ob ein JSON-Parser vorher läuft, ob Proxy oder Middleware Body oder Header verändern können und ob das Secret sicher aus Konfiguration geladen wird statt im Repository zu liegen. Bei eigener Implementierung gehört außerdem ein geeigneter zeitkonstanter Vergleich dazu.

Eine Signaturprüfung, die lokal funktioniert, aber hinter dem Produktions-Proxy andere Daten sieht, ist keine verlässliche Kontrolle.

Replay-Schutz ist nicht dasselbe wie Duplikat-Schutz

Ein korrekt signierter Request kann trotzdem unerwünscht sein, wenn er alt ist und erneut abgespielt wird. Stripe signiert deshalb einen Zeitstempel mit und beschreibt eine standardmäßige Toleranz von fünf Minuten in seinen Bibliotheken. GitHub empfiehlt, die eindeutige X-GitHub-Delivery-ID zu verwenden, um wiederholte Zustellungen erkennen zu können.

Replay-Schutz fragt, ob eine empfangene Zustellung zeitlich noch akzeptabel ist und zu einer legitimen Übertragung gehört. Duplikat-Schutz fragt dagegen, ob das fachliche Event bereits erfolgreich verarbeitet wurde.

Beides ist nötig. Eine legitime Wiederholungszustellung kann einen neuen Zeitstempel und eine gültige Signatur besitzen und trotzdem dasselbe Event enthalten. Wer nur die Signatur prüft, kann denselben Geschäftsvorgang mehrfach ausführen.

Exactly once ist meistens eine Eigenschaft Ihrer Verarbeitung, nicht des Transports

Webhook-Provider bauen Wiederholungen bewusst ein, weil Netze und Anwendungen ausfallen. Nehmen wir einen Zahlungs-Webhook: Der Provider sendet ein Erfolgsereignis. Ihr Server aktualisiert die Bestellung, startet den E-Mail-Versand – und stirbt, bevor die 200-Antwort den Provider erreicht. Aus Sicht des Providers ist nicht klar, ob die Verarbeitung erfolgreich war. Eine erneute Zustellung ist deshalb vernünftig.

Wenn der zweite Request nun erneut eine Rechnung erzeugt, denselben Gutschein verbraucht oder denselben Fulfillment-Prozess startet, war das Problem nicht der Retry. Es fehlte Idempotenz.

Ein solides Muster besteht darin, eine stabile Provider-Event-ID oder eine fachlich geeignete Idempotenzkennung persistent zu speichern und die gewünschte Zustandsänderung atomar daran zu koppeln. Ein späterer Retry darf dann erkennen: Dieses Event wurde bereits abgeschlossen – und ohne zweiten Geschäftseffekt erfolgreich antworten.

Nur eine In-Memory-Liste reicht dafür nicht. Nach einem Neustart wäre das Gedächtnis weg. Auch ein erst prüfen, dann später schreiben kann bei parallelen Requests zu Rennen führen. Die Datenbank- oder Queue-Grenze muss so gestaltet sein, dass dieselbe ID nicht gleichzeitig zweimal erfolgreich verarbeitet werden kann.

Reihenfolge darf keine versteckte Vorbedingung sein

Ein weiterer Klassiker ist Logik wie: Wenn subscription.created verarbeitet wurde, kann invoice.paid danach sicher darauf zugreifen. Stripe garantiert diese Reihenfolge nicht. GitHub dokumentiert ebenfalls, dass Webhook-Zustellungen außerhalb der ursprünglichen Ereignisreihenfolge eintreffen können.

Robuster ist eine zustandsorientierte Verarbeitung: Das Event identifiziert das betroffene Objekt, die Anwendung prüft den aktuellen bekannten Zustand, lädt bei Bedarf aktuelle Provider-Daten nach und führt Übergänge nur dann aus, wenn sie aus dem vorhandenen Zustand sinnvoll sind. Späte oder bereits überholte Events dürfen keinen Rollback auf einen älteren Zustand verursachen.

Damit wird die Integration weniger abhängig von Timing und Netzwerkglück.

Schnell bestätigen, langsam arbeiten

Webhook-Endpoints sind schlechte Orte für lange Geschäftsprozesse. GitHub empfiehlt eine schnelle 2xx-Antwort und bei aufwendiger Verarbeitung eine Queue. Stripe empfiehlt ebenfalls, schnell erfolgreich zu antworten, bevor komplexe Logik einen Timeout verursachen kann.

Ein robustes Modell sieht deshalb häufig so aus: Empfang → Signatur prüfen → Event identifizieren → dauerhaft einreihen → schnell 2xx antworten → asynchron verarbeiten.

Der entscheidende Teil ist dauerhaft. Ein 200, bevor das Event verlässlich gespeichert oder an eine belastbare Queue übergeben wurde, kann Datenverlust erzeugen. Umgekehrt kann lange synchrone Verarbeitung unnötige Retries provozieren. Die Grenze muss bewusst gewählt werden: Wann gilt ein Event aus Sicht Ihrer Anwendung als sicher angenommen?

Fünf Red Flags für einen Webhook-Review

1. Geschäftslogik läuft vor der Signaturprüfung

Dann verarbeitet die Anwendung potenziell nicht authentifizierte Requests.

2. Der Handler speichert keine Event- oder Delivery-ID

Dann fehlt meist eine belastbare Grundlage für Duplikaterkennung und Incident-Analyse.

3. Jeder Fehler endet trotzdem mit 200

Das verhindert zwar Retries, kann aber reale Events still verlieren. Ob ein 2xx richtig ist, hängt davon ab, ob das Event bereits sicher übernommen wurde.

4. Ein Timeout führt zwangsläufig zu doppelten Nebenwirkungen

Dann ist der Geschäftsvorgang nicht idempotent genug für ein System mit Wiederholungszustellung.

5. Niemand weiß, wie das Signing Secret rotiert wird

Secrets sind kein Einmal-Setup. Stripe unterstützt beispielsweise eine Übergangsphase mit mehreren aktiven Signaturen beim Rotieren. Ein Team sollte wissen, wie Rotation ohne Ausfall funktioniert.

Zuverlässigkeit braucht auch Betriebsdaten

Guter Code allein reicht nicht. Sinnvoll sind unter anderem Metriken für empfangene Events nach Typ, Signaturfehler getrennt von Anwendungsfehlern, Queue-Lag, Verarbeitungsdauer, Retry- und Duplikatrate, das Alter des ältesten unverarbeiteten Events und dauerhaft fehlgeschlagene Jobs. Ebenso wichtig ist eine nachvollziehbare Korrelation zwischen Provider-Event, interner Job-ID und Geschäftsobjekt.

Gerade null Events seit mehreren Stunden kann wichtiger sein als eine hohe Fehlerrate. Ein kaputter DNS-Eintrag, ein Zertifikatsproblem oder eine versehentlich geänderte Route erzeugt möglicherweise keinen Fehler in Ihrer Anwendung, weil der Request sie nie erreicht.

Was Website-Pflichtencheck an dieser Grenze prüfen würde

Wenn Webhooks Teil eines kritischen Website- oder SaaS-Prozesses sind, betrachten wir nicht nur die sichtbare Oberfläche. Ein technischer Check kann Erreichbarkeit, TLS, Signaturprüfung, Raw-Body-Verarbeitung, Secret-Handhabung, Replay- und Duplikatschutz, Retry-Verhalten, Idempotenz, Queue-Grenzen, Logs und Monitoring einbeziehen.

Dabei muss nicht jeder Endpoint dieselbe Architektur haben. Ein Newsletter-Webhook hat andere Auswirkungen als ein Zahlungs-, Benutzer- oder Fulfillment-Webhook. Entscheidend ist, dass die Schutzmaßnahmen zur tatsächlichen Geschäftsfolge eines Fehlers passen.

Der bessere Test ist nicht: Kommt ein Event an?

Testen Sie stattdessen dieselbe Event-ID zweimal, relevante Events in vertauschter Reihenfolge, eine gültige Payload mit ungültiger Signatur, einen zu alten signierten Request sofern der Provider Zeitstempel unterstützt, einen Worker-Absturz nach einer Zustandsänderung, eine erneute Zustellung nach Timeout, eine Secret-Rotation sowie Queue-Ausfall oder Backlog.

Wenn dabei unklar wird, was zweimal passieren darf und was als Geschäftseffekt nur einmal auftreten darf, ist genau diese Unsicherheit der Befund.

Ein Webhook ist nicht zuverlässig, weil er gestern 200 zurückgegeben hat. Er ist zuverlässig, wenn Wiederholung, Verspätung, Ausfall und Manipulationsversuche keine überraschenden Geschäftseffekte erzeugen.

Wenn Ihre Website oder Ihr SaaS von solchen Integrationen abhängt, kann Website-Pflichtencheck diese Übergänge technisch mitprüfen – bevor ein Retry zum Kundenproblem wird.