Idempotente Webhook-Verarbeitung: Delivery-IDs, Retry-Zeitpläne der Anbieter und schnelle Antworten

Worum es geht

Jeder Anbieter benennt ein Feld zur Deduplizierung, doch das Retry-Verhalten dahinter ist nicht austauschbar. Die Delivery-ID von GitHub (X-GitHub-Delivery) identifiziert eine Zustellung, und "if you request a redelivery, the X-GitHub-Delivery header will be the same as in the original delivery." Die GitHub-Dokumentation hält zudem klar fest: "GitHub does not automatically redeliver failed webhook deliveries, but you can handle failed deliveries manually or by writing code". Ein Empfänger, der eine Zustellung verpasst (dazu zählt jede Antwort, die länger als 10 Sekunden dauert), muss das selbst bemerken und über die Oberfläche oder die REST-API eine erneute Zustellung auslösen. Diese erreicht nur kürzlich erfolgte Zustellungen (die Seiten von GitHub nennen derzeit sowohl 3 als auch 7 Tage). Bei Stripe ist es umgekehrt: Der Webhook-Leitfaden warnt, "webhook endpoints might occasionally receive the same event more than once," empfiehlt, verarbeitete Event-IDs zu protokollieren (und für den seltenen Fall zweier separater Event-Objekte anhand der ID von data.object plus event.type zu deduplizieren) und dokumentiert automatische Wiederholungen "for up to three days with an exponential back off in live mode" (in einer Sandbox drei Wiederholungen über wenige Stunden). Manuelles erneutes Senden ist bis zu 15 Tage im Dashboard und bis zu 30 Tage über die CLI möglich. Die Events API von Slack wiederholt "a failed request up to 3 times in a gradually increasing timetable": fast sofort, dann nach 1 Minute, dann nach 5 Minuten. Jeder Versuch erhält einen Header x-slack-retry-num (1, 2 oder 3) sowie einen Header x-slack-retry-reason, der den Grund nennt (http_timeout, http_error und so weiter). Eine Antwort ausserhalb von 2xx mit x-slack-no-retry: 1 beendet weitere Versuche. Die Spezifikation Standard Webhooks empfiehlt genau dieses Muster allgemein: "Use the webhook-id header as an idempotency key to prevent accidentally processing the same webhook more than once (e.g. save the IDs in redis for 5 minutes)."

Warum es wichtig ist

Wird dasselbe Event zweimal verarbeitet, kann das zu doppelten Abbuchungen, doppelten Benachrichtigungen oder doppelten Zustandsänderungen führen. Eine unbekannte Retry-Policy (oder eine fehlende, die man vorausgesetzt hat) verursacht entweder doppelte Nebeneffekte oder lässt Events unbemerkt verloren gehen.

So wird es angewendet

• Verarbeitete Kennungen (Delivery-ID, Event-ID oder webhook-id) mit einer Ablaufzeit speichern, die mindestens so lang ist wie das Neuzustellungsfenster des Anbieters: mindestens 7 Tage bei GitHub, 3 Tage für die automatischen Wiederholungen von Stripe (bis zu 30 Tage, falls jemand manuell erneut sendet) und mehr als die rund sechs Minuten Retry-Spanne bei Slack.
• Schnell bestätigen (2xx innerhalb von 10 Sekunden bei GitHub, innerhalb von 3 Sekunden bei Slack, "quickly" bei Stripe) und Arbeit mit Nebeneffekten erst nach der Bestätigung in einer Queue ausführen. So löst ein langsamer nachgelagerter Aufruf keinen Timeout auf Anbieterseite und damit keine unerwünschte Wiederholung aus.
• Speziell bei GitHub nicht davon ausgehen, dass eine verpasste oder fehlgeschlagene Zustellung von selbst noch einmal eintrifft; stattdessen Monitoring oder einen geplanten erneuten Abruf der letzten Zustellungen einrichten.
• Den Retry-Reason-Header eines Anbieters (sofern vorhanden, wie bei Slack) in die Logs übernehmen; er zeigt, ob der Empfänger oder das Netzwerk die Wiederholung verursacht hat.

Stolpersteine

Deduplizierung anhand eines Hashes der Payload statt anhand der Kennung des Anbieters: Payloads können sich legitim wiederholen (zwei identische Transaktionen mit geringem Betrag), während IDs sich nie wiederholen. Ebenso falsch ist die Annahme, das Retry-Fenster von Stripe oder Slack sei kurz genug, dass ein In-Memory-Dedup-Cache pro Prozess genüge; ein Neustart zwischen zwei Wiederholungen löscht den Eintrag.