Idempotentność Webhooka: Gdy Stripe Wysyła To Samo Zdarzenie Prowizji Trzy Razy

Przez 14 miesięcy logowaliśmy każdego webhooka Stripe na thMenu: 312 z 100.000 zdarzeń przybyło z tym samym event_id dwa lub trzy razy. To obietnica "at-least-once delivery" Stripe w konkretnych liczbach — bez idempotentności trzy duplikaty w księdze prowizji.

Dlaczego To Samo Zdarzenie Przychodzi Trzy Razy

Jeśli Stripe nie otrzyma odpowiedzi 2xx w ciągu ~10 sekund, ponawia próbę. Timeouty TCP, cold starty lambda, przejściowe awarie DNS, nawet udane przetwarzanie z zerwanym połączeniem — wszystko wyzwala ponowne próby.

Trzy częste scenariusze: cold start Cloudflare Workers >10s, transakcja D1 batch zatwierdzona ale połączenie zerwane, lub ręczne "resend" w dashboardzie Stripe.

Wzorzec INSERT-Claim

Obrona thMenu to tabela stripe_webhook_events z event_id PRIMARY KEY. Pierwsza akcja: INSERT. Błąd unique constraint 23505 = duplikat — 200 OK no-op.

Krytyczne: claim musi poprzedzać logikę biznesową, aby uniknąć race condition.

Race Condition: Zdarzenia Poza Kolejnością

Prawdziwy incydent: customer.subscription.updated przybyło 800ms przed checkout.session.completed. UPDATE dotknął 0 wierszy. Fix: rollback claim, zwrot 503, Stripe ponawia.

FAQ

Weryfikacja podpisu przed czy po claim? Przed. Verify jest tani, zapis DB drogi.

Jak długo przechowywać wiersze idempotentności? Stripe gwarantuje 30 dni retry; my trzymamy 90 dni.

Czy Stripe ponawia w nieskończoność? Nie, maksymalnie 3 dni.

Czy to było pomocne? Udostępnij.