Idempotence Webhook: Quand Stripe Envoie Le Même Événement de Commission Trois Fois

Sur 14 mois nous avons loggé chaque webhook Stripe sur thMenu: 312 sur 100.000 événements sont arrivés avec le même event_id deux ou trois fois. C'est la promesse "at-least-once delivery" de Stripe en chiffres concrets — sans idempotence, trois doublons dans votre ledger de commission.

Pourquoi Le Même Événement Arrive Trois Fois

Si Stripe ne reçoit pas de réponse 2xx dans les ~10 secondes, il retry. Timeouts TCP, cold starts lambda, échecs DNS transitoires, même un traitement réussi suivi d'un drop de connexion avant l'écriture de la réponse — tout déclenche des retries.

Trois scénarios sont fréquents: cold start Cloudflare Workers >10s, transaction D1 batch committée mais connexion coupée, ou clic manuel "resend" dans le dashboard Stripe.

Le Pattern INSERT-Claim

La défense de thMenu est la table stripe_webhook_events avec event_id PRIMARY KEY. Première action du handler: INSERT. Erreur unique constraint 23505 = doublon — 200 OK no-op.

Critique: le claim doit précéder la logique métier. Sinon race condition: deux workers traitent en parallèle.

Race Condition: Événements Désordonnés

Incident production réel: customer.subscription.updated est arrivé 800ms avant checkout.session.completed. UPDATE a affecté 0 lignes. Fix: rollback du claim, retour 503, Stripe retry.

FAQ

Vérifier la signature avant ou après le claim? Avant. Verify est rapide, écriture DB coûteuse.

Combien de temps retenir les lignes d'idempotence? Stripe garantit 30 jours; nous gardons 90 jours pour audit.

Stripe retry à l'infini? Non, maximum 3 jours.

Cet article vous a été utile ? Partagez-le.