Stripe-Webhooks: Ein Event nur einmal sehen reicht nicht

Evergreen-Praxisleitfaden, kein Wochenlaunch: Stripe garantiert keine Ereignisreihenfolge und beschreibt wiederholte Lieferungen. Die Signaturprüfung benötigt den unveränderten Request-Body. Das sind Eingangseigenschaften, noch keine vollständige Verarbeitungsarchitektur. (Stripe)

Drei verschiedene Schlüssel

Stripe dokumentiert Idempotenzschlüssel für Wiederholungen schreibender API-Aufrufe. Dieser Mechanismus ersetzt weder Signaturprüfung noch die fachliche Definition einer einmaligen Wirkung. (Stripe)

Erst dauerhaft annehmen, dann die Arbeit fortsetzen

Der Empfang sollte kurz bleiben, darf aber nicht bloss «OK» sagen und die einzige Kopie des Ereignisses im Arbeitsspeicher behalten. Ein mögliches Zielbild ist die dauerhafte Aufnahme in eine private Ereignisliste mit eindeutiger Event-ID und anschliessend verlässlicher Weitergabe an die Verarbeitung. Schlägt die Aufnahme fehl, braucht der Sender eine Fehlerantwort statt einer falschen Empfangsbestätigung.

Illustratives Zielbild, kein ausführbarer Produktionscode:
Eingang:
  Signatur am unveränderten Body prüfen
  Event dauerhaft aufnehmen (eindeutige Event-ID)
  verlässliche Weiterverarbeitung sicherstellen
  Empfang bestätigen

Verarbeitung:
  betroffenen Auftrag und Zielzustand bestimmen
  Übergang unter Nebenläufigkeitskontrolle prüfen
  Absicht und Geschäftseffekt-Schlüssel dauerhaft sichern
  externe Aktion kontrolliert ausführen
  Ergebnis oder unklaren Ausgang nachvollziehbar ablegen

Wie Datenbank und Warteschlange gemeinsam abgesichert werden, ist eine konkrete Architekturfrage. Eine separate Queue-Nachricht nach einem Datenbank-Commit kann beispielsweise verloren gehen, wenn der Prozess dazwischen endet. Ein transaktionales Outbox-Muster ist eine mögliche Lösung, aber ebenfalls erst nach vollständiger Implementierung und Prüfung belastbar.

Ein Auftrag ist nicht dasselbe wie eine einzelne Wirkung

Ein nur nach Auftragsnummer deduplizierter Ablauf könnte jede spätere Änderung verschlucken. Sinnvoller ist eine zur Fachregel passende Identität. In einem rein illustrativen Shop wären «Auftrag 123 als bezahlt verarbeiten» und «Erstattung R für Auftrag 123 verarbeiten» verschiedene Wirkungen. Die konkrete Identität muss insbesondere Teilzahlungen, Erstattungen und Rücknahmen berücksichtigen.

Ebenso wenig sollte eine späte Nachricht einen neueren geprüften Zustand blind überschreiben. Vor einer Änderung muss die Integration feststellen, welchen Übergang sie gerade ausführen darf und ob die vorhandenen Angaben ausreichen. Wo nötig wird der aktuelle Zustand beim Anbieter abgefragt; er wird nicht aus der Ankunftsreihenfolge geraten.

Ein Timeout lässt das Ergebnis offen

Wenn die Gegenstelle die Aktion ausgeführt hat, aber die Antwort verloren geht, kennt die Integration ihren Ausgang noch nicht. Eine Wiederholung mit neuer Identität könnte eine zweite Wirkung auslösen. Der Wiederanlauf muss deshalb dieselbe beabsichtigte Aktion erkennen, einen geeigneten Idempotenzmechanismus verwenden und bei unklarem Zustand nachschlagen, statt Erfolg oder Fehlschlag zu erfinden.

• Dieselbe Lieferung trifft erneut ein: Aufnahme und Folgearbeit müssen eindeutig bleiben.
• Zwei Worker bearbeiten gleichzeitig denselben Auftrag: Fachregel und Sperr-/Transaktionsgrenze müssen standhalten.
• Ein anderer Eventtyp beschreibt denselben erreichten Zustand: keine zweite gleiche Geschäftswirkung.
• Eine legitime spätere Korrektur trifft ein: sie darf nicht durch zu grobe Deduplizierung verschwinden.
• Die externe Aktion endet mit Timeout: unklaren Ausgang sichtbar machen und kontrolliert auflösen.

Abgleich ist Teil des Betriebs

Auch ein sorgfältiger Ereignisfluss braucht eine Möglichkeit, offene und widersprüchliche Fälle zu finden. Eine Arbeitsliste mit Auftrag, letzter bestätigter Wirkung und ungeklärtem Ausgang ist dafür nützlicher als ein reiner HTTP-Erfolgszähler. Die verantwortliche Person muss erkennen können, welche Fälle ohne erneute Aussenwirkung nachgeprüft werden dürfen.

Das Modell verspricht kein universelles «exactly once» über fremde Systeme. Seine Abnahme besteht aus nachvollziehbaren Fachzuständen und gezielt geprüften Fehlerfällen. Für diesen Leitfaden wurden keine Zahlungen ausgelöst und keine Integration als produktiv getestet.