ADR-0012 — Webhooks HelloAsso — idempotence via helloassoid
| Statut | Accepté |
|---|---|
| Date | 2025-08-10 |
| Auteurs | Julien Jorry |
Contexte
HelloAsso peut rejouer un webhook (timeout réseau, retry exponentiel côté HelloAsso). Un double traitement crée de la monnaie (création silencieuse de eMLc). Il faut une clé d'idempotence stable et unique par paiement.
Décision
La colonne helloassoid (UUID HelloAsso du paiement) est UNIQUE dans la table de traçabilité. Le webhook handler fait SELECT ... FOR UPDATE sur cette ligne avant tout traitement. Si la ligne existe déjà traitée, retour 200 immédiat sans rejouer.
Conséquences positives
- Idempotence stricte garantie en base.
- Double traitement impossible.
- Audit : trace par
helloassoid.
Conséquences négatives
- Dépendance à la stabilité de l'ID HelloAsso (vérifié auprès de HelloAsso).
- Verrou pessimiste = sérialisation des webhooks d'un même paiement.
Alternatives examinées
- Hash du payload — rejeté : HelloAsso modifie parfois des métadonnées entre rejeux.
- Timestamp + montant — rejeté : pas unique.
Références
- webhooks.html
docs/helloasso/INTEGRATION_HELLOASSO_KOHINOS.md