Webentwicklung

Zuverlässige Webhook-Empfänger für kleine Anwendungen — Prüfen, speichern, bestätigen, dann verarbeiten

Geschrieben von Adam Muiz 26 Aug 2026 Aktualisiert: 26 Aug 2026 12 Min. gelesen

Ein Webhook-Endpunkt kann beinahe trivial wirken: einen HTTP-POST entgegennehmen, JSON dekodieren, einen Datensatz aktualisieren und 200 zurückgeben. Die schwierige Frage stellt sich, sobald einer dieser Schritte unterbrochen wird. Was geschieht, wenn die Anfrage gefälscht ist, der Anbieter sie erneut sendet, der Prozess nach der Antwort abstürzt oder zwei zusammengehörige Ereignisse in unerwarteter Reihenfolge eintreffen?

Das sind keine Randfälle, die sich hinter einem größeren Server verbergen lassen. Es sind Grenzen zwischen unabhängigen Systemen, von denen keines das andere vollständig beobachten kann. Ein zuverlässiger Empfänger benötigt deshalb mehr als eine Route und einen JSON-Parser. Er braucht ein kleines Protokoll, das festlegt, was vertrauenswürdig ist, was aufbewahrt werden muss, wann bestätigt werden darf und wie sich Arbeit sicher wiederholen lässt.

Dieser Artikel entwickelt ein solches empfangsseitiges Protokoll für eine kleine Anwendung. Er setzt kein bestimmtes Framework und keinen bestimmten Anbieter voraus, denn Signaturformate, Header, Wiederholungspläne und Zeitlimits unterscheiden sich. Das Ziel ist ein übertragbares Design, ergänzt um jene Stellen, an denen die Dokumentation des jeweiligen Anbieters Vorrang vor allgemeinen Empfehlungen haben muss.

Eine Zustellung ist nicht dasselbe wie abgeschlossene Arbeit

Ein Webhook wird üblicherweise als HTTP-Callback beschrieben: Ein Dienst sendet ein Ereignis an den Endpunkt eines anderen Dienstes. Die Standard-Webhooks-Spezifikation bezeichnet dies als eine Art „umgekehrte API“. Der Produzent initiiert die Anfrage, der Konsument empfängt sie.

Dieser HTTP-Austausch und die fachliche Arbeit der Anwendung hängen zusammen, sind aber nicht dieselbe Transaktion. Eine 2xx-Antwort besagt, dass die HTTP-Anfrage gemäß den geltenden Semantiken und dem Vertrag des Anbieters erfolgreich war. Sie kann nicht beweisen, dass später eine E-Mail versendet, ein Konto aktualisiert oder ein Aufruf einer externen API letztlich erfolgreich abgeschlossen wurde. RFC 9110 definiert HTTP-Semantik; daraus wird keine Garantie für einen unbeobachteten Hintergrundablauf.

Diese Unterscheidung legt zwei getrennte Phasen nahe:

Annahme: Die Anfrage authentifizieren, über ihre Zulässigkeit entscheiden und sie dauerhaft sichern.
Verarbeitung: Die beabsichtigte fachliche Wirkung anwenden, behebbare Fehler wiederholen und das Ergebnis festhalten.

Beide Phasen in einer langen Anfrage zusammenzufassen kann bei sehr kleinem Umfang funktionieren, schafft aber eine ungünstige Fehlergrenze. Dauert die Verarbeitung zu lange, kann beim Anbieter ein Timeout auftreten und eine Wiederholung beginnen, obwohl der erste Versuch noch läuft. GitHub dokumentiert beispielsweise ein Antwortfenster von zehn Sekunden und empfiehlt asynchrone Verarbeitung; diese Zahl ist eine Regel von GitHub und kein allgemeines Webhook-Zeitlimit. Auch Stripe fordert Empfänger dazu auf, vor komplexer Logik eine erfolgreiche Antwort zurückzugeben.

Die Reihenfolge im Empfänger: bewahren, prüfen, speichern, bestätigen, verarbeiten

Ein sinnvoller Empfänger lässt sich als kurze Abfolge beschreiben:

Den unveränderten Request-Body und die erforderlichen Header lesen, ohne den Body zu verändern.
Die Signatur des Anbieters, den signierten Zeitstempel und weitere erforderliche Metadaten prüfen.
Nicht unterstützte Ereignistypen oder eindeutig ungültige Payloads ablehnen.
Einen Inbox-Datensatz unter einem kontextbezogenen eindeutigen Schlüssel dauerhaft speichern.
Die vom Anbieter erwartete erfolgreiche Antwort zurückgeben.
Einen Worker den Inbox-Datensatz übernehmen und die fachliche Operation ausführen lassen.
Den Erfolg oder einen kontrollierten Fehler erfassen, der wiederholt oder untersucht werden kann.

Die Reihenfolge ist entscheidend. Eine Prüfung nach der Aktualisierung kommt zu spät. Eine Antwort vor der dauerhaften Speicherung erzeugt eine Lücke, in der der Prozess ein Ereignis bestätigen und anschließend dessen einzige Kopie verlieren kann. Aufwendige Arbeit vor der Antwort macht den Zustellversuch des Produzenten von der Latenz jeder nachgelagerten Abhängigkeit abhängig.

„Dauerhaft“ muss nicht zwangsläufig einen großen Message Broker bedeuten. Für eine kleine Anwendung kann eine Inbox-Tabelle in derselben Datenbank genügen. Entscheidend ist, dass eine erfolgreiche Bestätigung erst auf einen festgeschriebenen Datensatz folgt und nicht lediglich auf einen Eintrag im Prozessspeicher. Eine eigene Queue kann diese Aufgabe ebenfalls erfüllen, sofern ihre Bestätigung tatsächlich bedeutet, dass die Nachricht gemäß den benötigten Garantien gespeichert wurde.

Die tatsächlich gesendeten Bytes prüfen

Eine öffentliche Webhook-Route ist eine öffentliche Eingabe. HTTPS schützt die Verbindung, weist aber allein nicht nach, dass die Anfrage vom behaupteten Anbieter stammt. GitHub und Stripe empfehlen sowohl ein Webhook-Secret als auch eine Signaturprüfung. Standard Webhooks spezifiziert ebenfalls signierte Nachrichtenmetadaten und Payloads.

Ein naheliegender Fehler besteht darin, JSON zuerst zu parsen und anschließend eine neu serialisierte Fassung zu prüfen. Leerzeichen, Escape-Sequenzen und die Formatierung von Schlüsseln können sich ändern, obwohl die geparsten Daten dieselbe Bedeutung haben. Sowohl die Dokumentation von Stripe als auch die Standard-Webhooks-Spezifikation warnen davor, dass die Prüfung von den ursprünglichen Bytes des Bodys abhängen kann. Die sichere Regel lautet, den unveränderten Body bis zum Abschluss der Prüfung zu bewahren und den vom Anbieter dokumentierten Aufbau der signierten Inhalte exakt einzuhalten.

Für diesen Schritt gibt es kein verantwortbares universelles Codebeispiel. Anbieter unterscheiden sich bei Header-Namen, Kodierungen, signierten Feldern, Secret-Rotation und Zeitstempelregeln. Ein gepflegtes SDK des Anbieters ist häufig besser als selbst geschriebene Kryptografie. Ist eine manuelle Prüfung unvermeidbar, muss der aktuelle Algorithmus des Anbieters exakt umgesetzt werden, einschließlich eines zeitkonstanten Signaturvergleichs, sofern dieser vorgeschrieben ist.

Ein signierter Zeitstempel und ein stabiler Bezeichner lösen unterschiedliche Probleme. Ein Aktualitätsfenster kann eine alte, erneut übermittelte Anfrage ablehnen und damit das Replay-Risiko verringern. Eine Ereignis- oder Zustellungs-ID kann eine Anfrage identifizieren, die die Anwendung bereits angenommen hat. Der Empfänger benötigt in der Regel beide Prüfungen. Dabei muss der Bezeichner auf den Anbieter, das Konto oder den Endpunkt sowie den vom Anbieter beschriebenen Ereignisnamensraum begrenzt werden. Anzunehmen, dass die IDs aller Anbieter global eindeutig sind, ist weder erforderlich noch sicher.

Eine dauerhafte Inbox als Grenze für Duplikate verwenden

Doppelte Zustellungen sind verbreitet genug, dass sowohl GitHub als auch Stripe Bezeichner oder Verfahren zum Erkennen wiederholter Ereignisse dokumentieren. HTTP POST ist laut RFC 9110 nicht von sich aus idempotent. Darf derselbe Payload bei zweimaligem Empfang nicht zweimal abrechnen, veröffentlichen oder Ressourcen bereitstellen, muss die Anwendung diese Eigenschaft selbst herstellen.

Ein minimaler Inbox-Datensatz könnte Folgendes enthalten:

eine lokale Datensatz-ID;
Anbieter sowie Endpunkt- oder Kontokontext;
die Ereignis- oder Zustellungs-ID des Anbieters;
Ereignistyp und Zeitstempel des Anbieters;
Empfangszeit und Verarbeitungsstatus;
eine Versuchszahl und eine begrenzte Fehlerzusammenfassung;
den Payload oder einen geschützten Verweis darauf, jedoch nur bei begründeter Aufbewahrung.

Eine Eindeutigkeitsbedingung der Datenbank auf der kontextbezogenen Anbieter-ID ist stärker als die Abfolge „prüfen, dann einfügen“ im Anwendungscode. Zwei gleichzeitige Zustellungen können beide eine vorherige Abfrage passieren; erst die Speicherbedingung lässt dieses Rennen an einer einzigen Grenze entscheiden. Der Pfad für Duplikate sollte normalerweise bestätigen, dass das bestehende Ereignis angenommen wurde, und die vom Anbieter erwartete Erfolgsantwort zurückgeben, statt die fachliche Wirkung erneut auszuführen.

Bei der Aufbewahrung des Payloads ist Zurückhaltung angebracht. Ein vollständiger Payload kann Wiederherstellung und Prüfung erleichtern, aber auch persönliche oder sensible Daten enthalten. Ein schlankes Ereignis kann einen späteren API-Aufruf erfordern, während ein Snapshot den gesendeten Zustand festhält. Standard Webhooks erörtert diesen Zielkonflikt, ohne eine Form allgemein für richtig zu erklären. Der Empfänger sollte nur aufbewahren, was seine Anforderungen an Wiederherstellung, Prüfung und Rechtfertigung verlangen, diese Daten wie andere Anwendungsdaten schützen und Secrets oder vollständige Payloads nicht in gewöhnliche Logs schreiben.

Idempotenter Empfang ist keine universelle Exactly-once-Verarbeitung

Die Inbox kann sicherstellen, dass ein Ereignis des Anbieters genau einem lokalen Annahmedatensatz zugeordnet wird. Sie kann nicht jede Fehlergrenze beseitigen.

Angenommen, ein Worker liest ein angenommenes Ereignis, ruft einen externen E-Mail- oder Abrechnungsdienst auf und stürzt ab, bevor er die Inbox-Zeile als abgeschlossen markiert. Bei der Wiederholung kann er allein anhand der lokalen Zeile nicht erkennen, ob der externe Dienst den ersten Aufruf ausgeführt hat. Die nächste Ebene benötigt daher eine eigene Strategie: einen vom nachgelagerten API akzeptierten Idempotency Key, einen lokal und transaktional prüfbaren Zustandsübergang oder einen Abgleich mit dem maßgeblichen System.

Deshalb ist „exactly once“ als beiläufiges Versprechen zu stark. Ein ehrlicheres Ziel lautet:

jedes identifizierte Ereignis in genau einen dauerhaften lokalen Datensatz aufnehmen;
jeden fachlichen Übergang nach Möglichkeit wiederholungssicher gestalten;
weiterhin mehrdeutige Ergebnisse erkennen;
einen kontrollierten Abgleich oder eine kontrollierte Wiederholung ermöglichen.

Einige Operationen lassen sich von Natur aus leicht wiederholen, etwa das Setzen einer Zeile auf einen bekannten Zustand. Andere, beispielsweise das Erhöhen eines Zählers oder der Aufruf eines Systems ohne Idempotenzunterstützung, erfordern zusätzliches Design. Die Ereignis-ID kann daran beteiligt sein, doch ihre bloße Speicherung macht nicht jede nachgelagerte Wirkung idempotent.

Die Reihenfolge der Ereignisse nicht stillschweigend voraussetzen

Wiederholungen, parallele Worker und Netzwerkverzögerungen können die Reihenfolge von Ankunft und Abschluss verändern. Stripe dokumentiert ausdrücklich, dass seine Ereignisse nicht garantiert in ihrer Erzeugungsreihenfolge eintreffen. Andere Anbieter können andere Verträge anbieten; maßgeblich bleibt daher deren jeweilige Dokumentation.

Wenn die Reihenfolge wichtig ist, kann ein Event Handler eine Ressourcenversion, eine vom Anbieter gelieferte Ereignissequenz oder eine aktuelle Abfrage über dessen API verwenden. Keine Variante ist automatisch die beste. Das Abrufen des aktuellen Zustands kann mehrere ältere Ereignisse in einem Abgleich zusammenführen, fügt aber eine Netzwerkabhängigkeit hinzu und kann historische Details verlieren. Eine strikte sequenzielle Verarbeitung bewahrt die Historie, benötigt jedoch eine definierte Reaktion auf fehlende Ereignisse. Die richtige Wahl hängt davon ab, ob die Anwendung den neuesten Zustand, jeden Übergang oder beides benötigt.

Entscheidend ist, die Annahme ausdrücklich festzuhalten. Ein Handler, der die Ankunftsreihenfolge stillschweigend für wahr hält, kann korrekt wirken, bis die erste Wiederholung ein neueres Ereignis überholt.

Die Bestätigung sollte schnell, aber nicht verfrüht sein

„Schnell antworten“ wird manchmal als „antworten, bevor irgendetwas gespeichert wurde“ verstanden. Das tauscht das Timeout-Risiko lediglich gegen das Risiko eines Datenverlusts. Die sinnvollere Grenze lautet: Innerhalb der Anfrage nur die begrenzte Annahmearbeit ausführen, sie festschreiben und danach antworten.

Die Annahme sollte langsamen E-Mail-Versand, Bildverarbeitung, umfangreiche API-Aufrufe und mehrstufige fachliche Abläufe vermeiden. Sie kann dennoch die Signaturprüfung, grundlegende Schema- und Ereignistypprüfungen sowie einen kurzen dauerhaften Schreibvorgang umfassen. Schlägt dieser Schreibvorgang fehl, würde eine Erfolgsantwort den Produzenten zum Ende seiner Wiederholungen veranlassen, obwohl der Empfänger nichts bewahrt hat. Eine Fehlerantwort kann eine weitere Zustellung auslösen, auf die die Grenze zur Duplikaterkennung gerade vorbereitet ist.

Die Behandlung von Statuscodes hängt vom Anbieter ab. Standard Webhooks betrachtet 2xx als erfolgreiche Zustellung und beschreibt andere Antworten als Fehler, während einzelne Anbieter ihr Verhalten bei Timeout, Weiterleitung und Wiederholung selbst dokumentieren. Der Empfänger sollte diesen Vertrag bewusst umsetzen. Eine Erfolgsantwort bedeutet „dieser Empfänger hat die Verantwortung übernommen“, nicht zwingend „alle Folgen sind bereits abgeschlossen“.

Fehler sichtbar und Wiederholungen kontrolliert halten

Ein asynchroner Worker hält den Endpunkt reaktionsfähig, kann Fehler aber auch aus dem Blickfeld verschieben. Eine nützliche Inbox benötigt beobachtbare Zustände wie pending, processing, completed und failed, ergänzt um Zeitstempel und begrenzte Versuchszahlen. Für einen nach einem Worker-Absturz in processing hängen gebliebenen Datensatz ist eine Wiederherstellungsregel erforderlich.

Nur Fehler sollten wiederholt werden, die sich mit der Zeit bessern könnten. Ein vorübergehender Netzwerkfehler unterscheidet sich von einem Payload mit einem der Anwendung unbekannten Ereignistyp. Unbegrenzte sofortige Wiederholungen können ein einziges fehlerhaftes Ereignis in eine dauerhafte Last verwandeln. Backoff, eine Versuchsgrenze und ein Dead-Letter- oder Prüfstatus halten den Fehler endlich. Die Standard-Webhooks-Spezifikation empfiehlt außerdem Einblick in fehlgeschlagene Zustellungen und einen Mechanismus zur manuellen Wiederholung.

Eine manuelle Wiederholung darf weder die bisherige Prüfung noch Eindeutigkeitsregeln oder Prüfdatensätze umgehen. Sie sollte beantworten, wer die Wiederholung angefordert hat, welches gespeicherte Ereignis verwendet wurde und was der neue Verarbeitungsversuch bewirkt hat. Beobachtbarkeit ist nicht nur ein Dashboard: Eine kleine Anwendung kann mit strukturierten Logs, einer Abfrage nach alten ausstehenden Zeilen und einem Alarm beginnen, sobald Fehler einen sinnvollen Schwellenwert überschreiten.

Eine kompakte Checkliste für den Empfänger

Den Endpunkt über gültiges HTTPS bereitstellen und Signatur-Secrets außerhalb des Quellcodes aufbewahren.
Den unveränderten Request-Body bewahren und nach der aktuellen Dokumentation des Anbieters prüfen.
Signierte Zeitstempel, erwartete Ereignistypen, Anfragegröße und Schema vor der fachlichen Verarbeitung prüfen.
Eine dauerhafte Eindeutigkeitsbedingung entsprechend der Bezeichnersemantik des Anbieters begrenzen.
Angenommene Ereignisse festschreiben, bevor die Erfolgsantwort für den Anbieter gesendet wird.
Langsame Arbeit an einen Worker übergeben und jede Wirkung nach Möglichkeit wiederholungssicher gestalten.
Keine Reihenfolge voraussetzen, sofern der Anbieter sie nicht garantiert und das Design sie nicht durchsetzt.
Ausstehende, abgeschlossene, fehlgeschlagene und mehrdeutige Ergebnisse verfolgen, ohne unnötige Secrets oder Payload-Daten zu protokollieren.
Gültige Ereignisse, ungültige Signaturen, veraltete Zeitstempel, gleichzeitige Duplikate, Worker-Abstürze und nachgelagerte Timeouts testen.
Verfahren für Aufbewahrung, Wiederholung, Secret-Rotation und Abgleich dokumentieren.

Fazit

Bei einem zuverlässigen Webhook-Empfänger geht es weniger um das Annehmen von JSON als um eine wahrheitsgetreue Grenze. Vor dieser Grenze entscheidet die Anwendung noch, ob eine Anfrage authentisch und zulässig ist. Nach dem dauerhaften Commit in die Inbox hat sie Verantwortung übernommen und kann dem Produzenten die Annahme bestätigen. Die fachliche Verarbeitung wird anschließend zu einem sichtbaren, wiederholbaren Ablauf statt zu versteckter Arbeit innerhalb einer HTTP-Anfrage.

Dieses Design lässt Fehler verteilter Systeme nicht verschwinden und sollte nicht als automatische Exactly-once-Verarbeitung vermarktet werden. Es erreicht etwas Praktischeres: Duplikate, Abstürze, Verzögerungen und mehrdeutige Nebenwirkungen erhalten einen ausdrücklichen Platz im System. Für eine kleine Anwendung können eine sorgfältig begrenzte Inbox-Tabelle und ein Worker genügen. Die nächste Frage lautet nicht, wie viel Infrastruktur hinzukommen sollte, sondern welchen Fehler die Anwendung weiterhin weder erkennen noch sicher wiederholen kann.