Idempotente Webhooks: nie wieder doppelte Bestellungen

Webhooks kommen mindestens einmal an, oft mehrfach. Mit einem stabilen Idempotency-Key und einem Unique Constraint machst du daraus ein sauberes exactly-once, ohne Dubletten in Bestellungen, Rechnungen und Lager.

Warum ein Klick zwei Bestellungen erzeugt

Ein Kunde bezahlt einmal, dein System legt aber zwei Bestellungen an, verschickt zwei Rechnungen und bucht zweimal Lagerbestand ab. Ein Klassiker im E-Commerce, und die Ursache sitzt selten im Checkout. Sie sitzt im Webhook, der dein Backend ueber die Zahlung informiert.

Jeder ernstzunehmende Zahlungs- und Shop-Anbieter (Stripe, Shopify, PayPal, Mollie) liefert Webhooks mit einer Garantie namens at-least-once delivery. Das heisst: Ein Ereignis kommt mindestens einmal an, unter Umstaenden aber mehrfach. Ein Timeout, ein Netzwerkfehler oder ein Deploy, der die Antwort verzoegert, loest einen Retry aus. Der Provider weiss nicht, ob du das Ereignis schon verarbeitet hast, also schickt er es sicherheitshalber nochmal.

Die Loesung ist nicht, Retries abzuschalten (das kannst du nicht), sondern deinen Endpunkt idempotent zu machen: Egal wie oft dasselbe Ereignis eintrifft, das Ergebnis bleibt dasselbe wie bei genau einer Verarbeitung.

Was Idempotenz konkret bedeutet

Idempotenz ist ein Begriff aus der Mathematik. Eine Operation ist idempotent, wenn ihre mehrfache Anwendung dasselbe Resultat liefert wie eine einzelne. SET kontostand = 100 ist idempotent, UPDATE kontostand = kontostand + 100 nicht.

Genau das ist der Kern des Problems. Ein Webhook-Handler, der bei jedem Aufruf blind eine neue Zeile in orders schreibt, eine Mail feuert und den Bestand dekrementiert, ist die nicht-idempotente Variante. Kommt das Ereignis dreimal, hast du drei Bestellungen.

Du brauchst zwei Bausteine: einen stabilen Schluessel, der ein Ereignis eindeutig identifiziert, und einen Deduplizierungs-Speicher, der sich merkt, welche Schluessel schon durchgelaufen sind. Beides zusammen macht aus at-least-once ein praktisches exactly-once.

Der richtige Idempotency-Key: die Ereignis-ID des Anbieters

Der haeufigste Fehler ist ein selbst gebauter Schluessel aus dem Payload-Inhalt, etwa ein Hash ueber Betrag und E-Mail. Zwei legitime Bestellungen desselben Kunden ueber denselben Betrag kollidieren dann, und die zweite geht verloren. Nutze stattdessen die Ereignis-ID des Anbieters, die pro Ereignis stabil bleibt und ueber alle Retries hinweg gleich ist.

• Stripe: das Feld event.id (Format evt_1AbC...), bei jedem Retry desselben Events identisch.
• Shopify: der Header X-Shopify-Webhook-Id, konstant ueber Wiederholungen desselben Ereignisses.
• PayPal: das Feld id der Event-Notification (Format WH-...).

Wichtig: Der Schluessel muss vom Ereignis kommen, nicht vom einzelnen Zustellversuch. Manche Anbieter vergeben pro Versuch eine neue Delivery-ID. Die taugt nicht zur Deduplizierung, weil dann jeder Retry als neues Ereignis durchginge.

Die Dedup-Tabelle: ein Unique Constraint als Waechter

Der robusteste Speicher ist deine bestehende Datenbank, kein zusaetzlicher Dienst. Eine Tabelle mit dem Schluessel als Primary Key genuegt:

CREATE TABLE processed_events (event_id text PRIMARY KEY, processed_at timestamptz NOT NULL DEFAULT now());

Beim Eintreffen versuchst du, den Schluessel einzufuegen. Die Datenbank erzwingt die Eindeutigkeit atomar, du brauchst kein eigenes Locking:

INSERT INTO processed_events (event_id) VALUES ($1) ON CONFLICT (event_id) DO NOTHING RETURNING event_id;

Kommt keine Zeile zurueck (rowcount ist 0), hast du das Ereignis schon gesehen. Dann antwortest du sofort mit 200 OK und machst nichts weiter. Der entscheidende Trick: Fasse den Insert und die eigentliche Geschaeftslogik (Bestellung anlegen, Bestand buchen) in eine Datenbank-Transaktion. Bricht die Verarbeitung ab, wird auch der Dedup-Eintrag zurueckgerollt, und der naechste Retry darf es erneut versuchen. So markierst du nie ein Ereignis als erledigt, das in Wahrheit nie durchlief.

Race Conditions und die 200-in-5-Sekunden-Regel

Zwei Fallstricke bleiben. Erstens die Race Condition: Wenn dein Handler zu langsam antwortet, feuert der Provider einen Retry, waehrend der erste Aufruf noch laeuft. Jetzt verarbeiten zwei Prozesse dasselbe Ereignis gleichzeitig. Ein SELECT gefolgt von einem INSERT rettet dich hier nicht, weil beide den SELECT bestehen, bevor einer schreibt. Nur die atomare Variante (INSERT ... ON CONFLICT, oder in Redis SET key 1 NX EX 86400) ist race-sicher, weil die Eindeutigkeit an einer einzigen Stelle erzwungen wird.

Zweitens die Latenz. Shopify erwartet eine Antwort innerhalb von 5 Sekunden, sonst gilt die Zustellung als fehlgeschlagen und wird wiederholt. Wenn deine Verarbeitung laenger dauert (Rechnung erzeugen, E-Mail versenden, ERP-Abgleich), trenne Annahme und Verarbeitung: Schreibe das Ereignis in eine Queue, antworte sofort mit 200, und arbeite es in einem Hintergrund-Worker ab. Die Dedup-Logik greift dann im Worker. So provozierst du nicht durch eigene Langsamkeit die Retries, die du eigentlich verhindern willst.

Retry-Verhalten der Anbieter und Monitoring

Damit du die Groessenordnung kennst, hier das dokumentierte Retry-Verhalten:

• Stripe wiederholt fehlgeschlagene Webhooks mit exponentiellem Backoff bis zu drei Tage lang.
• Shopify versucht es 19 Mal ueber 48 Stunden, danach wird die Webhook-Subscription automatisch entfernt.
• PayPal wiederholt ueber mehrere Tage in wachsenden Abstaenden.

Drei Tage Retry heisst: Ein einziges Ereignis kann dutzende Male eintreffen, wenn dein Endpunkt zwischendurch wackelt. Ohne Idempotenz produziert jeder dieser Versuche eine Dubletten-Bestellung.

Zum Absichern: Logge zu jedem Ereignis die ID und ob es neu oder ein Duplikat war. Ein simples Zaehlverhaeltnis (Duplikate zu Ereignissen) zeigt sofort, wenn dein Endpunkt zu langsam wird und Retry-Stuerme ausloest. Und setz eine UNIQUE-Beschraenkung auch auf ein fachliches Feld (etwa die Zahlungs-ID in der orders-Tabelle) als zweites Netz, falls doch einmal ein Ereignis mit neuem Schluessel dieselbe Zahlung meldet.

Umsetzung in Kuerze

• Nimm die Ereignis-ID des Anbieters als Idempotency-Key, niemals einen Payload-Hash oder Zufallswert.
• Dedupliziere ueber einen Primary Key oder Unique Constraint, nicht ueber SELECT-dann-INSERT.
• Insert und Geschaeftslogik in eine Transaktion, damit ein Abbruch sauber zuruecklaeuft.
• Antworte in unter 5 Sekunden mit 200, schwere Arbeit in einen Worker auslagern.
• Zweites Netz: Unique Constraint auf der Zahlungs-ID in der Bestelltabelle.
• Pruefe die HMAC-Signatur, bevor du irgendetwas verarbeitest, sonst dedupliziert du gefaelschte Ereignisse gleich mit.

Mit diesen sechs Punkten wird aus einem fragilen Endpunkt ein belastbarer. Der Kunde bezahlt einmal, dein System reagiert genau einmal, egal wie oft der Provider anklopft.