Un client se plaint d'avoir été débité deux fois pour la même commande. En creusant les logs, on trouve deux appels à POST /webhooks/stripe avec le même event.id, reçus à quelques secondes d'intervalle. Le code de traitement n'avait rien prévu pour ce cas : chaque appel déclenchait la création d'une facture et l'envoi d'un email de confirmation. Ce n'est pas un bug exotique, c'est le comportement documenté et attendu de tous les fournisseurs de paiement sérieux (Stripe, PayPal, Adyen, Mollie...), et toute intégration webhook qui ne le gère pas explicitement double facturera un jour.
Pourquoi les webhooks arrivent en double
Les fournisseurs de paiement garantissent une livraison "at least once", jamais "exactly once". Le mécanisme est simple : le fournisseur envoie l'événement, attend un code HTTP 2xx dans un délai court (souvent quelques secondes), et si la réponse n'arrive pas à temps - timeout réseau, redémarrage du serveur pendant le traitement, latence d'une base de données en aval - il considère la livraison échouée et retente plus tard, avec un backoff exponentiel qui peut s'étaler sur plusieurs heures ou jours.
Le piège classique : votre serveur a bien traité l'événement et créé la facture, mais la réponse HTTP s'est perdue en route (coupure réseau, load balancer qui ferme la connexion), ou votre traitement a dépassé le timeout du fournisseur sans avoir échoué. Le fournisseur ne peut pas savoir si vous avez traité l'événement ou non, il ne voit que l'absence de 2xx. Il retente. Votre code, s'il n'est pas idempotent, retraite l'événement depuis zéro.
Diagnostiquer : confirmer que c'est bien un doublon
Avant de corriger, vérifier dans les logs applicatifs et dans le dashboard du fournisseur que l'event.id est identique entre les deux appels :
# Chercher les occurrences d'un même event.id dans les logs applicatifs
grep "evt_1Nk3x" /var/log/app/webhooks.log
2024-02-14T10:22:01Z webhook received event=evt_1Nk3x type=payment_intent.succeeded
2024-02-14T10:22:03Z invoice created order=4821 amount=4900
2024-02-14T10:22:41Z webhook received event=evt_1Nk3x type=payment_intent.succeeded
2024-02-14T10:22:43Z invoice created order=4821 amount=4900
Deux créations de facture pour le même event.id, 40 secondes d'écart : c'est une retentative, pas un bug du fournisseur. Si en revanche les event.id diffèrent mais correspondent à la même transaction logique, le problème est différent (le code applicatif a généré deux intents de paiement pour une même action utilisateur, souvent un double clic non protégé côté frontend) et se corrige ailleurs.
La correction : déduplication par clé idempotente avant tout effet de bord
Le principe est de vérifier, de façon atomique, si l'événement a déjà été traité, avant de déclencher le moindre effet de bord métier (création de facture, envoi d'email, crédit de compte).
CREATE TABLE processed_webhook_events (
event_id VARCHAR(255) PRIMARY KEY,
event_type VARCHAR(100) NOT NULL,
processed_at TIMESTAMPTZ NOT NULL DEFAULT now()
);
// webhook-handler.ts (NestJS / Node)
async function handleStripeWebhook(event: Stripe.Event, db: Pool) {
const client = await db.connect();
try {
await client.query('BEGIN');
// INSERT atomique : si event_id existe déjà, ON CONFLICT ne fait rien
// et rowCount vaut 0, ce qui nous dit "déjà traité".
const result = await client.query(
`INSERT INTO processed_webhook_events (event_id, event_type)
VALUES ($1, $2)
ON CONFLICT (event_id) DO NOTHING`,
[event.id, event.type],
);
if (result.rowCount === 0) {
await client.query('ROLLBACK');
logger.info(`Event ${event.id} already processed, skipping`);
return;
}
// Effets de bord métier, dans la même transaction que possible
if (event.type === 'payment_intent.succeeded') {
const intent = event.data.object as Stripe.PaymentIntent;
await createInvoiceForOrder(client, intent.metadata.order_id, intent.amount_received);
}
await client.query('COMMIT');
} catch (err) {
await client.query('ROLLBACK');
throw err;
} finally {
client.release();
}
}
Le point clé est l'INSERT ... ON CONFLICT DO NOTHING dans la même transaction que les effets de bord métier : si la facture est créée mais que le commit échoue (crash serveur juste après), la ligne processed_webhook_events n'existe pas non plus, donc le retraitement ultérieur recréera correctement la facture. Si l'insert réussit mais que le traitement métier échoue ensuite, le rollback annule les deux, et le prochain retry retraitera proprement. On évite ainsi l'état incohérent "événement marqué traité mais facture jamais créée".
Un point souvent négligé : répondre 2xx le plus vite possible, y compris sur un doublon détecté. Faire du traitement métier lourd (appel à un service tiers, génération de PDF) de façon synchrone dans le handler webhook augmente le risque de timeout côté fournisseur et donc le nombre de retries. Le pattern robuste consiste à faire la déduplication et l'enregistrement en base de façon synchrone, puis déléguer le traitement métier à une queue (BullMQ, SQS) traitée de façon asynchrone et elle-même idempotente.
Vérifier aussi la signature, pas seulement l'event.id
La déduplication seule ne protège pas contre un appel forgé. Chaque fournisseur signe ses payloads avec un secret partagé, et la vérification doit se faire sur le corps brut de la requête, avant tout parsing JSON :
import Stripe from 'stripe';
const sig = req.headers['stripe-signature'];
let event: Stripe.Event;
try {
// req.body doit être le Buffer brut, pas du JSON déjà parsé
event = stripe.webhooks.constructEvent(req.rawBody, sig, process.env.STRIPE_WEBHOOK_SECRET);
} catch (err) {
logger.warn(`Signature invalide: ${err.message}`);
return res.status(400).send('invalid signature');
}
Une erreur fréquente en Express/NestJS est de laisser un middleware body-parser JSON global transformer le corps avant que constructEvent ne puisse vérifier la signature sur les octets exacts envoyés par le fournisseur ; il faut une route dédiée avec express.raw() pour le endpoint webhook.
Quand la table de déduplication ne suffit pas
La table processed_webhook_events résout le doublon au niveau de l'événement webhook, mais ne résout pas le cas où deux événements différents (deux payment_intent.succeeded distincts) correspondent à la même intention métier - par exemple un utilisateur qui soumet deux fois un formulaire de paiement avant que le premier n'ait abouti. Ce cas se traite en amont, côté création du PaymentIntent, avec une clé d'idempotence fournie explicitement par votre application :
await stripe.paymentIntents.create(
{ amount: 4900, currency: 'eur', customer: customerId },
{ idempotencyKey: `order_${orderId}_attempt_1` },
);
Avec cette clé, Stripe lui-même garantit que des appels répétés avec la même clé renvoient le même PaymentIntent au lieu d'en créer un second, même en cas de retry réseau côté client. Les deux mécanismes (clé d'idempotence à la création, déduplication à la réception du webhook) sont complémentaires et couvrent des points de défaillance différents.
Livraison désordonnée et croissance de la table de déduplication
Deux cas limites apparaissent une fois la déduplication de base en place. D'abord, aucun fournisseur ne garantit l'ordre de livraison : un événement charge.refunded peut, dans de rares cas, être livré et traité avant l'événement payment_intent.succeeded correspondant, si les deux sont émis proches dans le temps et qu'une retentative dépasse l'autre dans la file. Baser les transitions d'état uniquement sur "le dernier événement reçu" est fragile ; il est plus sûr de faire relire par le handler l'état réel de la ressource concernée (interroger l'API du fournisseur pour le statut actuel du paiement, ou comparer des horodatages) plutôt que de supposer que les événements arrivent toujours dans l'ordre où ils ont été générés.
Ensuite, processed_webhook_events grossit indéfiniment si rien ne la purge, alors que la plupart des fournisseurs abandonnent les retentatives après une fenêtre bornée (Stripe arrête au bout de trois jours par défaut). Une tâche de purge périodique élimine ce risque sans réintroduire de risque de double traitement :
-- À exécuter chaque nuit : les événements plus anciens que la fenêtre
-- de retry du fournisseur peuvent être supprimés sans risque
DELETE FROM processed_webhook_events
WHERE processed_at < now() - interval '7 days';
Les sept jours ici sont une marge volontairement supérieure à la fenêtre de retry documentée du fournisseur, pas un chiffre arbitraire ; vérifier la durée maximale de retry réellement documentée par le fournisseur avant de choisir ce seuil.
À retenir
Un webhook de paiement sera livré plus d'une fois, c'est une garantie du protocole, pas une anomalie. Le traitement doit vérifier, de façon atomique et dans la même transaction que les effets de bord, si l'event.id a déjà été traité avant de créer une facture ou d'envoyer un email. Ajouter en complément une clé d'idempotence côté création de l'intent de paiement pour couvrir les doubles soumissions côté client, et répondre 2xx rapidement en déléguant le traitement lourd à une queue asynchrone.
