Webhook-Idempotenz und Retries: Keys, Fristen, Seiteneffekte

KURZ GESAGT: Die meisten Absender wiederholen bei Timeouts, 5xx und Netzfehlern; bei den übrigen stellen Sie selbst neu zu. Rechnen Sie also mit At-least-once: Jedes Event bekommt einen stabilen Key, der Verarbeitungsstatus wird vor allen Seiteneffekten gespeichert, und der Dedup-Speicher hält mindestens so lange wie die längste Retry-Spanne des Absenders. Abgeschlossene Keys bekommen nur noch 2xx.

Ablauf beim Webhook-Empfang: Idempotency-Key nachschlagen; ist er abgeschlossen, 2xx zurückgeben; ist er in Bearbeitung, Warte- oder Konfliktregel anwenden; ist er neu, zuerst speichern, dann Seiteneffekte ausführen und als abgeschlossen markieren. Darunter vergleichen zwei Zeitleisten das Retry-Fenster des Absenders mit der Dedup-Aufbewahrung beim Empfänger, die mindestens gleich lang sein muss.
Abbildung 1. Dedup-Prüfung vor den Seiteneffekten. Die Aufbewahrung muss die Retry-Spanne des Absenders abdecken.

1.0 Absender wiederholen, Empfänger rechnen mit At-least-once

Ein Webhook, der bei Ihnen in den Timeout lief, ist womöglich längst verarbeitet. Das weiß der Absender nicht, also schickt er ihn noch einmal. Bei 500er-Antworten und schlichten Netzfehlern passiert dasselbe. Wer so baut, als käme jedes Event genau einmal, bekommt doppelte E-Mails, doppelte Lagerbewegungen oder zwei ERP-Belege für eine Zahlung.

Wie lange Anbieter es weiter versuchen, ist sehr unterschiedlich. Stripe zum Beispiel wiederholt Live-Webhook-Zustellungen bis zu drei Tage lang mit exponentiellem Backoff. GitHub stellt fehlgeschlagene Zustellungen nicht automatisch neu zu; alles aus den letzten drei Tagen können Sie in der Oberfläche oder per API erneut senden. Lesen Sie die Hinweise des Anbieters zu Retries und Neuzustellung und legen Sie die Dedup-Aufbewahrung nach dem längsten Fenster aus, das für Sie zählt. Die Annahme „wir antworten schnell, also gibt es keine Retries“ trägt nicht.

2.0 Ein stabiler Key

QuelleTypischer KeyHinweis
Event-ID des Anbietersevt_…, Delivery-GUIDBevorzugen, wenn sie pro logischem Event eindeutig ist
Zusammengesetzt(provider, event_id)Wenn ein System Webhooks mehrerer Anbieter annimmt
HeaderIdempotency-Key, X-GitHub-DeliveryIdempotency-Key für eigene ausgehende APIs. GitHub behält bei einer Neuzustellung dieselbe X-GitHub-Delivery-GUID; sie kennzeichnet also das Event, nicht den einzelnen Versuch
Fachobjekt(event_type, object_id)Nötig, wenn der Anbieter für dieselbe Änderung zwei Event-Objekte senden kann

Den Key mit Unique-Constraint speichern (oder per atomarem bedingtem Schreiben). Schwierig wird es bei Nebenläufigkeit: Zwei Worker sehen beide „nicht vorhanden“, solange nicht der Insert selbst die Sperre ist.

3.0 Status statt Erledigt-Flag

ZustandBedeutungBei erneuter Zustellung desselben Keys
processingAngenommen, Arbeit läuft (optional mit Lease / Owner)Warten, Konflikt zurückgeben oder an den laufenden Versuch anhängen; keinen zweiten Pfad mit Seiteneffekten starten
completedGespeichert, Seiteneffekte erledigtSofort 2xx; keine Seiteneffekte
failed_retryableWeicher Fehler; erneuter Versuch unkritischMit Backoff wiederholen, weiter unter demselben Key
failed_terminalOhne menschliches Eingreifen aussichtslosAlarm; nicht endlos automatisch wiederholen

processing wird im selben dauerhaften Schreibvorgang gesetzt, der den Key zum ersten Mal annimmt, also vor jeder E-Mail, jeder Abbuchung und jedem ERP-Aufruf. completed erst dann, wenn diese Seiteneffekte selbst dauerhaft festgehalten sind (oder die Outbox-Zeile, die sie anstößt, committet ist).

4.0 Retry-Fenster und Dedup-Aufbewahrung

Zwei Zeitspannen müssen zusammenpassen:

  1. Retry-Fenster des Absenders: wie lange der Anbieter (oder Ihr eigenes Skript zur Neuzustellung) dasselbe Event erneut senden kann.
  2. Dedup-Aufbewahrung beim Empfänger: wie lange Keys und Ergebnisse gespeichert bleiben, damit ein spätes Duplikat erkannt wird.

Die Aufbewahrung muss ≥ dem Retry-Fenster sein, das Sie akzeptieren. Laufen Keys früher ab, sieht ein später Retry wie ein neues Event aus. Manuelle Neuzustellung reicht meist weiter zurück: Stripe wiederholt automatisch bis zu drei Tage, im Dashboard lässt sich ein Event aber 15 Tage lang erneut senden, per CLI 30 Tage. Wenn der Betrieb nach Ablauf Ihrer Aufbewahrung noch aus dem Dashboard neu anstößt, gibt es zwei Wege: die Aufbewahrung verlängern oder einen frischen Key plus einen ausdrücklichen Abgleich verlangen.

5.0 Erst speichern, dann bestätigen

Unangenehm ist dieser Fall: Ihr Handler hat die Arbeit erledigt, dann bricht die Verbindung ab, bevor der Absender 2xx sieht. Der Absender wiederholt. Stand der Erfolg nur im Speicher, laufen die Seiteneffekte ein zweites Mal.

In dieser Reihenfolge schreiben wir:

  • Zuerst das Event (oder eine Outbox-Zeile) und den Status processing / completed schreiben.
  • 2xx erst nach dem Commit dieses Schreibvorgangs zurückgeben.
  • Nicht idempotente Seiteneffekte aus dem dauerhaften Datensatz anstoßen, nach der Dedup-Prüfung.
  • Dauern die Seiteneffekte lange, nach der dauerhaften Annahme bestätigen und den Rest asynchron erledigen, weiterhin unter demselben Key und derselben Zustandsmaschine.

6.0 Seiteneffekte hinter der Sperre

Alles, was sich schwer rückgängig machen lässt (E-Mail senden, Karte belasten, ERP-Beleg übertragen, Ticket anlegen), läuft erst, nachdem der Key beansprucht ist. Wiederholungen eines completed-Keys überspringen diesen Pfad und melden Erfolg. Ist ein Seiteneffekt auf der Gegenseite selbst nicht idempotent, bekommt er einen eigenen fachlichen Key (Auftragsnummer, Rechnungsnummer), damit ein zweiter Push keinen zweiten Beleg erzeugt.

7.0 Reihenfolge bei At-least-once-Zustellung

Viele Anbieter garantieren keine Reihenfolge. Ein updated-Event kann vor created eintreffen, oder ein Retry einer älteren Payload folgt auf eine neuere. Idempotenz allein hilft da nicht. Pro Fachobjekt eine Version, Sequenznummer oder updated_at führen und veraltete Schreibvorgänge ignorieren, oder vor einer Änderung am lokalen Zustand die aktuelle Ressource beim Anbieter abrufen.

8.0 Was geloggt und alarmiert wird

  • Den Dedup-Speicher nach Key indizieren, damit „haben wir evt_… schon verarbeitet?“ eine einzige Abfrage ist.
  • Jeden Versuch loggen: Key, Ergebnis (Duplikat / processing / completed / failed), Latenz, Anzahl der Versuche.
  • Zahlungs- und personenbezogene Daten bleiben aus gemeinsamen Logs draußen; wir loggen einen Digest und unsere interne ID.
  • Alarm bei Keys, die länger als der Lease in processing hängen, und bei plötzlich vielen Duplikaten (oft ein Retry-Sturm des Absenders nach einem Ausfall).

Wenn Sie Webhook-Empfänger für Zahlungen, ERP oder Geräte-Clouds bauen, siehe Web, Cloud und Geräteverwaltung, oder Projekt besprechen.

Quellen

Häufige Fragen

Unser Anbieter schreibt, jedes Event komme genau einmal. Brauchen wir trotzdem einen Dedup-Speicher?

In der Praxis gilt fast immer At-least-once: Timeouts, 5xx-Antworten und kurze Netzaussetzer lösen Wiederholungen aus. Erst ein stabiler Key und eine Aufbewahrungsfrist, die die längste Retry-Spanne des Anbieters abdeckt, verhindern doppelte Seiteneffekte, wenn dieselbe Payload erneut ankommt.

Was antworten wir, wenn ein Duplikat eintrifft, während der erste Versuch noch läuft?

Einen Konflikt oder ein kurzes Später-wieder-versuchen, je nachdem, was der Absender dokumentiert. Für denselben Key darf aber kein zweiter Pfad mit Seiteneffekten starten. Wir halten den Eintrag mit einem Lease (Owner und Ablaufzeit) im Status processing und setzen ihn erst auf completed, wenn Persistenz und Seiteneffekte abgeschlossen sind.

Wie lange sollten verarbeitete Keys aufbewahrt werden?

Mindestens so lange wie das automatische Retry-Fenster des Absenders, besser bis zum Ende einer veröffentlichten Frist für manuelle Neuzustellung. Läuft ein Key ab und kommt dasselbe Event noch einmal, hält der Empfänger es für neu und führt nicht idempotente Arbeit unter Umständen erneut aus.

Wir haben schon 200 zurückgegeben, aber die E-Mail oder der ERP-Push lief nie. Wie holen wir das nach?

Event und Verarbeitungsstatus gehören gespeichert, bevor 2xx rausgeht; die Seiteneffekte laufen dann aus diesem dauerhaften Datensatz oder einer Outbox. Wer Erfolg meldet, bevor der Schreibvorgang durch ist, hat nach einem lokalen Fehler nichts mehr, woraus er wiederherstellen kann, und der Absender hält das Event für zugestellt.

Events kommen manchmal in falscher Reihenfolge. Löst der Idempotency-Key das?

Der Key verhindert nur, dass dasselbe Event zweimal angewendet wird. Für die Reihenfolge braucht es eigene Regeln: veraltete Versionen per Sequenznummer oder updated_at verwerfen oder vor jeder Änderung am lokalen Zustand das aktuelle Objekt über die API des Anbieters holen.