Comment un événement Stripe devient un seul message

Entre Stripe et votre canal, il y a cinq décisions. Chacune est écrite dans le journal : vous savez toujours pourquoi un message est parti, ou non.

Stripe                        Paybell                        votre canal
   |                             |                               |
   |  événement + signature -->  |                               |
   |                             |  1. signature vérifiée        |
   |  <--- 400, pas Stripe ----  |     (fausse ? rien ne part)   |
   |                             |  2. déjà traité ? on s'arrête |
   |                             |  3. vos règles : type, montant|
   |                             |  4. même paiement qu'un       |
   |                             |     événement déjà annoncé ?  |
   |                             |  5. message  -------------->  |
   |                             |  <------------- 200 --------  |
   |  <--- 200, traité --------  |                               |
   |                             |  canal en panne ? Stripe est  |
   |  <--- 503, à renvoyer ----  |  prié de renvoyer             |
   |                             |  journal : ce qui est entré,  |
   |                             |  ce qui en a été fait, pourquoi|

1. Est-ce vraiment Stripe ?

Stripe signe chaque événement : il calcule un HMAC-SHA256 de l'horodatage et du corps exact avec la clé de signature de votre endpoint, et l'envoie dans l'en-tête Stripe-Signature. Paybell refait le calcul. Un résultat différent, un en-tête absent ou un horodatage de plus de cinq minutes : la requête est refusée (400) et votre canal n'entend rien. Tant que vous n'avez pas collé la clé de signature, tout événement est refusé pour cette raison, et Stripe le renvoie plus tard. Pour comprendre un échec chez vous, voyez le vérificateur de signature.

2. A-t-il déjà été traité ?

Stripe livre « au moins une fois » : le même événement peut arriver deux fois. Chaque identifiant d'événement est retenu par connexion, et une répétition reçoit un 200 sans second message.

3. Voulez-vous en entendre parler ?

Vos règles décident : types d'événements activés, montant minimum pour les paiements, mode test ou non. Un paiement sous votre minimum reste silencieux mais compte dans le résumé quotidien.

4. Est-ce encore le même paiement ?

Un paiement par carte via Checkout produit checkout.session.completed, payment_intent.succeeded et charge.succeeded, plus invoice.paid pour un abonnement. Ils partagent une intention de paiement ou une facture. Le premier arrivé est annoncé ; les autres sont notés « merged » dans le journal.

5. Le canal l'a-t-il pris ?

Si le canal répond par une erreur passagère (trop de requêtes, erreur serveur, pas de réponse à temps), Stripe reçoit un 503 et renverra l'événement, pendant trois jours au plus. Si le canal dit que le webhook n'existe plus, réessayer ne servirait à rien : l'événement est noté « refused » et le tableau de bord vous invite à vérifier l'adresse.

Ce qui tourne dessous

Paybell est une petite application sur Qu4zr : un endpoint HTTP qui vérifie et transmet, une base pour le journal, un coffre pour la clé qui chiffre vos secrets, et une horloge pour le résumé quotidien. Si vous avez besoin de la même chose entre deux autres systèmes, ou avec vos propres règles, c'est à cela que sert Qu4zr.