Checklist des webhooks de paiement idempotents pour dédupliquer les événements, gérer les retries et mettre à jour en toute sécurité factures, abonnements et droits d'accès.
Un webhook de paiement est un message que votre fournisseur de paiement envoie à votre backend quand quelque chose d'important se produit : un paiement réussi, une facture payée, un renouvellement d'abonnement ou un remboursement. C'est en gros le fournisseur qui dit « Voici ce qui s'est passé. Mettez à jour vos enregistrements. »
Les doublons arrivent parce que la livraison des webhooks est conçue pour être fiable, pas pour être « exactly once ». Si votre serveur est lent, fait timeout, retourne une erreur, ou est brièvement indisponible, le fournisseur relancera souvent le même événement. Vous pouvez aussi voir deux événements différents faire référence à la même action réelle (par exemple, un événement invoice et un événement payment liés à un même paiement). Les événements peuvent aussi arriver hors ordre, en particulier avec des suites rapides comme des remboursements.
Si votre handler n'est pas idempotent, il peut appliquer le même événement deux fois, ce qui cause des problèmes que les clients et les équipes financières remarquent immédiatement :
Ce n'est pas juste une « bonne pratique ». C'est la différence entre une facturation qui paraît fiable et une facturation qui génère des tickets support.
Le but de cette checklist est simple : traiter chaque événement entrant comme « appliquer au plus une fois ». Vous stockerez un identifiant stable pour chaque événement, gérerez les retries en toute sécurité et mettrez à jour factures, abonnements et entitlements de façon contrôlée. Si vous construisez le backend dans un outil no‑code comme AppMaster, les mêmes règles s'appliquent : il vous faut un modèle de données clair et un flux handler répétable qui reste correct sous retries.
Idempotence signifie que traiter la même entrée plusieurs fois produit le même état final. En termes de facturation : une facture est payée une seule fois, un abonnement est mis à jour une seule fois, et l'accès est accordé une seule fois, même si le webhook est livré deux fois.
Les fournisseurs relancent quand votre endpoint fait timeout, renvoie un 5xx, ou que le réseau tombe. Ces retries répètent le même événement. C'est différent d'un événement distinct qui représente un changement réel, comme un remboursement quelques jours plus tard. Les nouveaux événements ont des IDs différents.
Pour que cela fonctionne, il vous faut deux choses : des identifiants stables et une petite « mémoire » de ce que vous avez déjà vu.
La plupart des plateformes de paiement incluent un ID d'événement unique au webhook. Certaines incluent aussi un request ID, une idempotency key, ou un ID d'objet de paiement unique (comme un charge ou payment intent) dans le payload.
Stockez ce qui vous aide à répondre à la question : « Ai‑je déjà appliqué exactement cet événement ? »
Un minimum pratique :
L'idée clé est de stocker l'ID d'événement dans une table avec une contrainte d'unicité. Ensuite votre handler peut faire ceci en toute sécurité : insérer l'ID d'événement en premier ; s'il existe déjà, arrêter et retourner 200.
Conservez-les assez longtemps pour couvrir les retries tardifs et les enquêtes. Une fenêtre commune est de 30 à 90 jours. Si vous traitez des rétrofacturations, des litiges ou des cycles d'abonnement longs, conservez‑les plus longtemps (6 à 12 mois), puis purgez les lignes anciennes pour que la table reste rapide.
Dans un backend généré comme AppMaster, cela se traduit proprement par un modèle WebhookEvents simple avec un champ unique sur l'ID d'événement, plus un Business Process qui quitte tôt quand un duplicata est détecté.
Un bon handler de webhook est surtout un problème de données. Si vous pouvez enregistrer chaque événement fournisseur une seule fois, tout ce qui suit devient plus sûr.
Commencez par une table qui sert de registre de reçu. Dans PostgreSQL (y compris quand elle est modélisée dans AppMaster Data Designer), gardez‑la petite et stricte pour que les duplicatas échouent rapidement.
Voici une base pratique pour une table webhook_events :
provider (texte, par ex. "stripe")provider_event_id (texte, requis)status (texte, comme "received", "processed", "failed")processed_at (timestamp, nullable)raw_payload (jsonb ou texte)Ajoutez une contrainte d'unicité sur (provider, provider_event_id). Cette règle unique est votre principal garde‑fou de déduplication.
Vous voudrez aussi les IDs métiers que vous utilisez pour localiser les enregistrements à mettre à jour. Ceux‑ci diffèrent de l'ID d'événement webhook.
Exemples courants : customer_id, invoice_id, subscription_id. Conservez‑les comme texte car les fournisseurs utilisent souvent des IDs non numériques.
Conservez le payload brut pour pouvoir déboguer et retraiter plus tard. Les champs parsés facilitent les requêtes et le reporting, mais ne stockez que ce que vous utilisez réellement.
Une approche simple :
raw_payloadevent_type normalisé (texte) pour le filtrageSi un invoice.paid arrive deux fois, votre contrainte d'unicité bloque la seconde insertion. Vous avez toujours le payload brut pour l'audit, et l'ID de facture parsé facilite la localisation de la facture que vous avez mise à jour la première fois.
Un handler sûr est volontairement ennuyeux. Il se comporte de la même manière à chaque fois, même quand le fournisseur renvoie le même événement ou livre des événements hors ordre.
Vérifiez la signature et parsez le payload. Rejetez les requêtes qui échouent à la vérification de signature, ont un type d'événement inattendu ou qui ne peuvent pas être parsées.
Écrivez l'enregistrement d'événement avant de toucher aux données de facturation. Sauvegardez l'ID d'événement fournisseur, le type, le temps de création et le payload brut (ou un hash). Si l'ID d'événement existe déjà, traitez‑le comme un duplicata et arrêtez.
Mappez l'événement à un seul enregistrement « propriétaire ». Décidez ce que vous mettez à jour : invoice, subscription ou customer. Stockez les IDs externes sur vos enregistrements afin de pouvoir les rechercher directement.
Appliquez un changement d'état sûr. Ne faites avancer l'état que dans le sens prévu. Ne rétrogradez pas une facture payée parce qu'un tardif invoice.updated arrive. Enregistrez ce que vous avez appliqué (ancien état, nouvel état, horodatage, event ID) pour l'audit.
Répondez rapidement et consignez le résultat. Retournez le succès une fois que l'événement est enregistré en sécurité et soit traité soit ignoré. Logguez s'il a été traité, dédupliqué ou rejeté, et pourquoi.
Dans AppMaster, cela devient généralement une table de base de données pour les webhook events plus un Business Process qui vérifie « ID d'événement vu ? » puis exécute les étapes minimales de mise à jour.
Les fournisseurs relancent les webhooks quand ils n'obtiennent pas de réponse rapide de succès. Ils peuvent aussi envoyer des événements hors ordre. Votre handler doit rester sûr quand la même mise à jour arrive deux fois, ou quand un événement plus récent arrive avant un événement antérieur.
Une règle pratique : répondez vite, faites le travail plus tard. Traitez la requête webhook comme un reçu, pas comme l'endroit où exécuter de la logique lourde. Si vous appelez des API tierces, générez des PDF ou recalculez des comptes dans la requête, vous augmentez les timeouts et déclenchez plus de retries.
La livraison hors ordre est normale. Avant d'appliquer tout changement, utilisez deux contrôles :
Si vous avez déjà enregistré une facture comme payée et qu'un tardif « open » arrive, ignorez‑le. Si vous avez reçu « canceled » et plus tard un ancien « active » apparaît, conservez canceled.
Ignorez un événement lorsque vous pouvez prouver qu'il est obsolète ou déjà appliqué (même ID d'événement, horodatage plus ancien, priorité de statut inférieure). Mettez un événement en file lorsqu'il dépend de données que vous n'avez pas encore, comme une mise à jour d'abonnement arrivant avant que le client existe.
Un pattern pratique :
Dans AppMaster, cela correspond bien à une table webhook events plus un Business Process qui accuse rapidement la requête et traite les événements en file de façon asynchrone.
Une fois la déduplication gérée, le risque suivant est l'état de facturation scindé : la facture indique payée, mais l'abonnement est toujours en retard, ou l'accès a été accordé deux fois et jamais révoqué. Traitez chaque webhook comme une transition d'état et appliquez‑la en une mise à jour atomique.
Les factures peuvent passer par des états comme paid, voided et refunded. Vous pouvez aussi voir des paiements partiels. Ne « basculez » pas une facture selon l'événement arrivé en dernier. Stockez le statut courant ainsi que les totaux clés (amount_paid, amount_refunded) et n'autorisez que des transitions sûres vers l'avant.
Règles pratiques :
amount_refunded jusqu'au total de la facture ; ne le diminuez jamais.Les abonnements comprennent renouvellements, annulations et périodes de grâce. Conservez le statut de l'abonnement et les limites de période (current_period_start/end), puis déduisez les fenêtres d'entitlement à partir de ces données. Les entitlements doivent être des enregistrements explicites, pas un simple booléen.
Pour le contrôle d'accès :
Appliquez les mises à jour de facture, d'abonnement et d'entitlement dans une seule transaction de base de données. Lisez les lignes courantes, vérifiez si cet événement a déjà été appliqué, puis écrivez tous les changements ensemble. Si quelque chose échoue, faites rollback pour éviter de vous retrouver avec « facture payée » mais « pas d'accès », ou l'inverse.
Dans AppMaster, cela se traduit souvent par un Business Process unique qui met à jour PostgreSQL dans une voie contrôlée et écrit une entrée d'audit en même temps que le changement métier.
La sécurité des webhooks fait partie de la correction. Si un attaquant peut frapper votre endpoint, il peut essayer de créer de faux états « payés ». Même avec la déduplication, vous devez prouver que l'événement est réel et garder les données client sûres.
Validez la signature à chaque requête. Pour Stripe, cela signifie typiquement vérifier l'en‑tête Stripe-Signature, en utilisant le corps brut de la requête (pas un JSON réécrit), et rejeter les événements avec un horodatage ancien. Traitez l'absence d'en‑têtes comme un échec catégorique.
Validez les éléments de base tôt : méthode HTTP correcte, Content-Type, et champs requis (event id, type, et l'objet id que vous utiliserez pour localiser une facture ou un abonnement). Si vous construisez cela dans AppMaster, gardez le secret de signature dans des variables d'environnement ou une configuration sécurisée, jamais dans la base de données ou le code client.
Une checklist de sécurité rapide :
Loggez assez pour déboguer retries et litiges, mais évitez les valeurs sensibles. Stockez un sous‑ensemble sûr de PII : provider customer ID, ID utilisateur interne, et éventuellement un email masqué (comme a***@domain.com). Ne stockez jamais les données complètes de carte, adresses complètes ou en‑têtes d'autorisation bruts.
Logguez ce qui vous aide à reconstruire ce qui s'est passé :
Ajoutez une protection basique contre les abus : limitation de débit par IP et (si possible) par customer ID, et envisagez de n'autoriser que des plages IP connues du fournisseur si votre configuration le permet.
La plupart des bugs de facturation ne sont pas des erreurs de calcul. Ils arrivent quand on traite une livraison webhook comme un message unique et fiable.
Erreurs qui conduisent le plus souvent à des mises à jour dupliquées :
Un exemple simple : un événement de renouvellement arrive deux fois. La première livraison crée une ligne entitlement. Le retry crée une seconde ligne, et votre app voit « deux entitlements actifs » et accorde des sièges ou crédits en trop.
Dans AppMaster, la correction tient surtout au flux : vérifiez d'abord, insérez l'enregistrement d'événement avec une contrainte d'unicité, appliquez les mises à jour métier avec des vérifications d'état, et poussez les effets secondaires (emails, reçus) vers des étapes asynchrones pour éviter une tempête de retries.
Ce schéma paraît inquiétant, mais il est gérable si votre handler est sûr à relancer.
Un client est sur un plan mensuel. Stripe envoie un événement de renouvellement (par exemple invoice.paid). Votre serveur le reçoit, met à jour la base, mais prend trop de temps à retourner un 200 (cold start, base occupée). Stripe suppose un échec et retrie le même événement.
À la première livraison, vous accordez l'accès. Au retry, vous détectez que c'est le même événement et ne faites rien. Plus tard, un événement de remboursement arrive (par exemple charge.refunded) et vous révoquez l'accès une seule fois.
Voici une façon simple de modéliser l'état en base (tables que vous pouvez construire dans AppMaster Data Designer) :
webhook_events(event_id UNIQUE, type, processed_at, status)invoices(invoice_id UNIQUE, subscription_id, status, paid_at, refunded_at)entitlements(customer_id, product, active, valid_until, source_invoice_id)Après l'événement A (renouvellement, première livraison) : webhook_events reçoit une nouvelle ligne pour event_id=evt_123 avec status=processed. invoices est marqué payé. entitlements.active=true et valid_until avance d'une période de facturation.
Après l'événement A à nouveau (renouvellement, retry) : l'insertion dans webhook_events échoue (unicité event_id) ou votre handler voit qu'il est déjà traité. Aucune modification sur invoices ou entitlements.
Après l'événement B (remboursement) : une nouvelle ligne webhook_events pour event_id=evt_456. invoices.refunded_at est renseigné et status=refunded. entitlements.active=false (ou valid_until est mis à now) en utilisant source_invoice_id pour révoquer l'accès une seule fois.
Le détail important est le timing : la vérification de déduplication intervient avant toute écriture de grant ou revoke.
Avant d'activer les webhooks en production, vous voulez la preuve qu'un événement réel met à jour les enregistrements de facturation exactement une fois, même si le fournisseur l'envoie deux fois (ou dix fois).
Utilisez cette checklist pour valider votre configuration de bout en bout :
Vous n'avez pas besoin d'un gros dispositif d'observabilité pour commencer, mais vous avez besoin de signaux. Suivez‑les via logs ou tableaux de bord simples :
Si vous construisez cela dans AppMaster, gardez le stockage d'événements dans une table dédiée du Data Designer et faites de « marquer comme traité » un point de décision atomique dans votre Business Process.
Les tests sont l'endroit où l'idempotence se prouve. Ne testez pas seulement le happy path. Rejouez le même événement plusieurs fois, envoyez des événements hors ordre, et provoquez des timeouts pour que votre fournisseur retrie. La deuxième, troisième et dixième livraison ne devraient rien changer.
Préparez aussi le backfilling. Tôt ou tard vous voudrez retraiter des événements passés après une correction de bug, un changement de schéma ou un incident fournisseur. Si votre handler est vraiment idempotent, le backfilling devient « rejouer les événements via le même pipeline » sans créer de doublons.
Le support a aussi besoin d'un petit runbook pour que les incidents ne tournent pas en conjectures :
Si vous voulez l'implémenter sans écrire beaucoup de boilerplate, AppMaster (appmaster.io) vous permet de modéliser les tables de base et de construire le flux de webhook en Business Process visuel, tout en générant du code source réel pour le backend.
Essayez de construire le handler de webhook de bout en bout dans un backend généré no‑code et assurez‑vous qu'il reste sûr sous retries avant d'augmenter le trafic et les revenus.
Pourquoi mon fournisseur de paiement envoie-t-il plusieurs fois le même webhook ?Les livraisons en double de webhooks sont normales parce que les fournisseurs visent une livraison au moins une fois. Si votre endpoint met du temps à répondre, retourne un 5xx ou perd brièvement la connexion, le fournisseur renverra le même événement jusqu'à obtenir une réponse réussie.
Quelle est la meilleure façon de dédupliquer les événements webhook ?Utilisez l'ID d'événement unique fourni par le fournisseur (l'identifiant de l'événement webhook), pas le montant de la facture, l'horodatage ou l'email du client. Stockez cet ID d'événement avec une contrainte d'unicité pour que les retries soient détectés immédiatement et ignorés en toute sécurité.
Dois‑je sauvegarder l'événement avant de mettre à jour les enregistrements de facturation ?Insérez d'abord l'enregistrement de l'événement, avant de mettre à jour les factures, abonnements ou droits. Si l'insertion échoue parce que l'ID d'événement existe déjà, arrêtez le traitement et retournez un succès afin que les retries ne créent pas de doublons.
Combien de temps devrais‑je conserver les enregistrements de déduplication des webhooks ?Conservez-les assez longtemps pour couvrir les retries tardifs et pour permettre les enquêtes. Un défaut pratique est 30–90 jours, et plus long (par exemple 6–12 mois) si vous gérez des litiges, rétrofacturations ou cycles d'abonnement longs ; purgez ensuite les lignes anciennes pour garder les requêtes rapides.
Ai‑je vraiment besoin de la vérification de signature si je déduplique déjà les événements ?Vérifiez la signature avant de toucher aux données de facturation, puis parsez et validez les champs requis. Si la vérification de signature échoue, rejetez la requête et n'appliquez pas de changements de facturation, car la déduplication ne vous protégera pas contre des événements « payés » falsifiés.
Comment gérer les timeouts de webhook sans créer de doublons ?Privilégiez l'accusé de réception rapide après que l'événement est stocké en sécurité, et déplacez le travail lourd en arrière‑plan. Les gestionnaires lents provoquent plus de timeouts, ce qui entraîne davantage de retries et augmente le risque de mises à jour en double si quelque chose n'est pas totalement idempotent.
Que faire lorsque les événements arrivent hors ordre ?N'appliquez que des changements qui font avancer l'état, et ignorez les événements obsolètes. Utilisez les horodatages d'événement quand ils sont disponibles et une priorité de statut simple (par exemple, refunded ne doit pas être écrasé par paid, et canceled ne doit pas être écrasé par active).
Comment éviter d'accorder l'accès deux fois lorsqu'un webhook de renouvellement est réessayé ?Ne créez pas une nouvelle ligne d'entitlement à chaque événement. Utilisez une règle de type upsert comme « garantir une entitlement par utilisateur/produit/période (ou par abonnement) », puis mettez à jour les dates/limites, et enregistrez quel ID d'événement a causé le changement pour l'audit.
Pourquoi les mises à jour de facture et d'entitlement doivent‑elles être dans une seule transaction ?Écrivez les changements de facture, d'abonnement et d'entitlement dans une seule transaction de base de données afin qu'ils réussissent ou échouent ensemble. Cela évite des états divisés comme « facture payée » mais « accès non accordé », ou « accès révoqué » sans enregistrement de remboursement correspondant.
Puis‑je implémenter cela en toute sécurité dans AppMaster sans écrire de code backend personnalisé ?Oui. C'est une bonne solution : créez un modèle WebhookEvents avec un ID d'événement unique, puis construisez un Business Process qui vérifie « déjà vu ? » et sort tôt. Modélisez explicitement invoices/subscriptions/entitlements dans le Data Designer pour que les retries et replays n'engendrent pas de lignes dupliquées.
21 janv. 2026
8 min
20 janv. 20268 min
20 janv. 20268 minExpérimentez avec AppMaster avec un plan gratuit.
Lorsque vous serez prêt, vous pourrez choisir l'abonnement approprié.
