Aller au contenu
Retour à l’académie
Ingénierie8 min de lecture

Comprendre et fiabiliser les webhooks Stripe

Vérifier les signatures, enregistrer durablement les événements et maîtriser leur traitement.

Abderrahim Ben Jazia, PhDPar · Fondateur de FlowMRR, a créé puis revendu AIS (Avance Immédiate Services), logiciel agréé Urssaf d'avance immédiate du crédit d'impôtContenu relu :

Les webhooks Stripe informent votre application des changements liés aux abonnements, factures et paiements. Les livraisons peuvent se répéter ou arriver dans le désordre, et votre traitement peut échouer après réception. Prévoyez explicitement chacun de ces cas.

Avant de commencer

  • Un environnement de test Stripe et une CLI installée, authentifiée avec des identifiants de test uniquement.
  • Une route HTTP POST sous votre contrôle ; les exemples locaux utilisent localhost:4242/webhook.
  • Une base de données ou une file persistante, et un worker (processus de traitement) pour la production.

Périmètre

Ce guide explique comment concevoir un traitement fiable des webhooks et le tester en local. Le modèle officiel de Stripe vérifie les signatures mais n'enregistre pas durablement les événements : ajoutez-le avant la mise en production.

Étape 1

Ce qu'est vraiment un webhook

  1. STRIPE
    POST de l'événement
  2. HTTPS + signature
  3. ENDPOINT
    /webhook
    vérifie la signature
    2xx après enregistrement
  4. enregistrer, puis répondre 2xx
  5. FILE
    file de réception durable
  6. asynchrone, réessayable
  7. WORKER
    applique l'événement / l'état courant
  8. écriture idempotente
  9. BASE DE DONNÉES

Hors 2xx → Stripe renvoie le même event id

jusqu'à 3 jours en mode live · délai exponentiel · même contenu

Stripe → vérification → enregistrement durable → worker réessayable → effets idempotents. Répondez 2xx seulement après l'enregistrement.

Stripe envoie une requête HTTP POST décrivant un événement à l'URL configurée. Votre serveur vérifie l'événement et l'enregistre durablement ; un worker applique ensuite les changements métier. Sans réponse 2xx, Stripe renvoie le même événement pendant 3 jours maximum en mode live ; dans un environnement de test, il réessaie 3 fois en quelques heures.

Étape 2

Vérifier la signature à chaque requête

Vérifiez chaque signature avec le SDK officiel : stripe.webhooks.constructEvent(rawBody, signature, secret). Sans cette vérification, un tiers pourrait envoyer de faux événements. Si elle lève une exception, renvoyez 400 et ne traitez pas la requête.

Route webhook Express : vérifier, enregistrer, acquitter

import express from "express";
import Stripe from "stripe";

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);
const app = express();

// Corps brut sur cette route uniquement : déclarez express.json() APRÈS elle, ou sur les autres routes.
app.post("/webhook", express.raw({ type: "application/json" }), async (req, res) => {
  let event: Stripe.Event;
  try {
    event = stripe.webhooks.constructEvent(
      req.body,
      req.headers["stripe-signature"] as string,
      process.env.STRIPE_WEBHOOK_SECRET!,
    );
  } catch {
    return res.sendStatus(400); // signature invalide ou absente
  }

  try {
    // Une livraison en double conserve la ligne existante ; le worker la réessaie si elle est inachevée.
    await db.query(
      `INSERT INTO stripe_events (event_id, type, payload, status, received_at, next_retry_at)
       VALUES ($1, $2, $3, 'pending', now(), now())
       ON CONFLICT (event_id) DO NOTHING`,
      [event.id, event.type, event],
    );
  } catch {
    return res.sendStatus(500); // non enregistré : laissez Stripe renvoyer l'événement
  }

  res.sendStatus(200); // enregistré durablement ; le traitement a lieu dans le worker
});

db représente votre client Postgres. Dans une route du App Router de Next.js, passez await req.text() à constructEvent au lieu d'appeler req.json().

Modèle officiel de webhook Stripe

Attention

La vérification exige le corps brut de la requête. Un express.json() global, ou req.json() dans Next.js, le transforme avant et fait échouer la vérification. Conservez le corps brut uniquement sur la route webhook. Si le corps a été transformé, le SDK lève l'erreur « No signatures found matching the expected signature for payload ».

Étape 3

S'abonner uniquement aux événements utiles

Dans Workbench → Webhooks → Create event destination, choisissez des événements snapshot (instantanés) si votre intégration lit event.data.object. Sélectionnez les événements que votre intégration sait traiter, par exemple customer.subscription.created, customer.subscription.updated, customer.subscription.deleted, invoice.paid, invoice.payment_failed et customer.updated. Documentez le rôle de chaque traitement. Évitez tous les événements sans politique de gestion définie.

Écoute locale en environnement de test

stripe listen --events invoice.paid,invoice.payment_failed --forward-to localhost:4242/webhook

Tests uniquement : vérifiez le compte CLI et les identifiants de test ; n'ajoutez jamais --live. Lancez votre serveur à cette adresse ou adaptez-la. Utilisez le secret de signature de l'écoute dans l'environnement serveur, pas celui d'une destination du tableau de bord. Gardez ce secret privé et laissez ce terminal ouvert.

Étape 4

Enregistrer avant d'acquitter, puis traiter en arrière-plan

Vérifiez la signature, enregistrez l'événement dans une file de réception durable (table ou file où chaque événement est enregistré avant la réponse), puis répondez rapidement avec 2xx après cet enregistrement. Si la persistance échoue, ne confirmez pas la réception. Le worker prend en charge le travail en attente de façon atomique (un seul worker peut prendre un événement à la fois), applique les changements et réessaie les échecs. Chaque prise en charge est un bail (la prise en charge expire si le worker plante) : un arrêt brutal ne laisse pas un événement bloqué. Une tâche en mémoire lancée avant la réponse 200 ne constitue pas un enregistrement durable.

Astuce

Une table d'événements en attente peut remplacer une file si elle gère la prise en charge atomique, l'expiration des baux, les nouvelles tentatives et la surveillance des erreurs. Distinguez received_at de processed_at.

Worker : prendre en charge un événement en attente

UPDATE stripe_events
SET status = 'processing',
    claim_expires_at = now() + interval '5 minutes',
    attempt_count = attempt_count + 1
WHERE event_id = (
  SELECT event_id FROM stripe_events
  WHERE ((status = 'pending' AND next_retry_at <= now())
     OR (status = 'processing' AND claim_expires_at < now()))
    AND attempt_count < 10
  ORDER BY received_at
  LIMIT 1
  FOR UPDATE SKIP LOCKED
)
RETURNING *;

En cas de succès, passez status à 'processed' et renseignez processed_at. En cas d'échec, repassez à 'pending' avec next_retry_at = now() + délai et last_error ; après la 10e tentative, passez plutôt à 'failed' pour qu'il apparaisse comme travail bloqué (étape 8). FOR UPDATE SKIP LOCKED permet à plusieurs workers de tourner sans prendre le même événement.

Étape 5

Gérer l'idempotence

LIVRAISON N°1
evt_1ABC123
invoice.paid
LIVRAISON N°2 (NOUVEL ENVOI)
evt_1ABC123
même id
INSERT INTO stripe_events
(event_id, type, payload)
ON CONFLICT (event_id) DO NOTHING
PREMIÈRE ÉCRITURE
✓ ligne créée
travail en attente créé
DOUBLON
réutiliser la ligne existante
réessayer si inachevé
Un event_id unique évite les doublons de stockage, pas les effets métier répétés. Marquez traité uniquement après réussite.

Un event_id unique évite les doublons dans la table de réception, mais une insertion réussie ne signifie PAS un traitement réussi. En cas de nouvelle livraison, réutilisez l'enregistrement en attente plutôt que d'abandonner un travail inachevé. Prenez-le en charge atomiquement et rendez les effets métier idempotents, y compris les appels externes avec des clés adaptées. Renseignez processed_at uniquement après un traitement réussi ; un échec reste à réessayer. Coordonnez les écritures en base et les effets externes pour qu'un arrêt entre les deux ne répète ni prélèvement ni notification.

Étape 6

Prévoir le désordre et les accès concurrents

Les événements peuvent arriver dans le désordre et plusieurs traitements se concurrencer. Relisez l'état actuel via l'API Stripe pour synchroniser une vue courante, mais conservez l'événement immuable pour les effets historiques ou comptables. L'état actuel ne remplace pas ce qui s'est passé à la date de l'événement. Sérialisez les traitements par objet et appliquez des règles de version ou de rapprochement adaptées ; l'ordre de réception n'est pas l'ordre causal.

Attention

Testez l'ordre de livraison inversé et les traitements concurrents d'un même objet, pas seulement les identifiants d'événements dupliqués.

Étape 7

Prévoir une reprise contrôlée

Construisez une reprise à partir des événements enregistrés durablement. Une nouvelle livraison doit réutiliser l'enregistrement en attente et reprendre le travail inachevé, sans être écartée par la déduplication sur l'identifiant. Limitez cette opération aux personnes autorisées, journalisez-la et préservez l'idempotence des effets métier. Toute réexécution volontaire d'un événement déjà traité doit être une opération distincte et vérifiée. Pour un événement isolé, vous pouvez aussi le renvoyer depuis le tableau de bord Stripe ou avec stripe events resend evt_…. Stripe conserve les événements 30 jours : listez-les via l'API pour combler les écarts.

Étape 8

Surveiller la livraison et le traitement séparément

Suivez les réponses hors 2xx, l'ancienneté du travail en attente, les prises en charge expirées, les erreurs de traitement et les écarts de rapprochement. Une réponse 200 prouve seulement la réception, pas l'achèvement. Enregistrez un statut structuré, le nombre de tentatives, la prochaine échéance et la dernière erreur ; alertez sur les tâches bloquées et prévoyez une correction autorisée. Définissez des règles de conservation, d'accès et de masquage des données personnelles et des secrets.

Générer un échec de test

stripe trigger invoice.payment_failed

Dans un second terminal du même environnement de test, lancez cette commande pendant l'écoute. Elle crée des objets de test, sans prélèvement réel ni reprise d'un événement existant. Vérifiez la réponse HTTP et l'achèvement du traitement durable. Testez séparément les doublons, l'ordre et la reprise après incident.

Vérifiez les signatures, enregistrez durablement les événements et rendez les effets idempotents. Distinguez synchronisation courante et effets historiques, surveillez le travail inachevé et testez la reprise après échec.

Vérifications finales

Suivez vos données Stripe

Connectez Stripe à FlowMRR pour synchroniser les données de facturation et suivre le revenu récurrent. Vérifiez l'état de connexion et la dernière synchronisation : la configuration seule ne prouve pas le traitement.

Questions

Faut-il gérer chaque événement envoyé par Stripe ?+

Non. Sélectionnez uniquement les événements nécessaires à votre application et documentez leur traitement. Les types non sélectionnés ne sont pas livrés à cette destination.

Quelle architecture de base pour les webhooks ?+

Prévoyez une table de réception durable avec event_id unique, type, données de l'événement, received_at, processed_at, statut, expiration de la prise en charge, nombre de tentatives, prochaine échéance et dernière erreur. La prise en charge atomique évite les traitements concurrents ; l'identifiant unique évite les doublons de stockage, pas les effets métier répétés. Renseignez processed_at uniquement après réussite et contrôlez conservation et accès.

Exposer les webhooks derrière un CDN ou directement ?+

Les deux conviennent si la route conserve le corps brut et l'en-tête de signature, accepte les requêtes Stripe sans contrôle interactif et ne met pas les réponses en cache. Testez la signature derrière le CDN ou le mandataire réellement déployé. Aucun réglage spécial Cloudflare universel n'est requis pour les webhooks Stripe.

Combien de temps Stripe renvoie-t-il un webhook en échec ?+

En mode live, Stripe renvoie un événement pendant 3 jours maximum, avec un délai exponentiel, jusqu'à recevoir une réponse 2xx ; dans un environnement de test, il réessaie 3 fois en quelques heures. Chaque renvoi porte le même event id et le même contenu : une file de réception durable avec un event_id unique les absorbe.

Pourquoi la vérification de signature d'un webhook Stripe échoue-t-elle ?+

Le plus souvent, le corps a été transformé avant la vérification : l'erreur « No signatures found matching the expected signature for payload » signifie que constructEvent n'a pas reçu les octets bruts exacts. Utilisez express.raw() sur la route webhook, ou await req.text() dans Next.js. Vérifiez aussi le secret de signature : l'écoute de la CLI Stripe a le sien, différent de celui de la destination du tableau de bord.

Comment gérer les événements webhook Stripe en double ?+

Enregistrez chaque événement avec un event_id unique grâce à INSERT … ON CONFLICT (event_id) DO NOTHING. Un doublon réutilise alors la ligne existante : le worker la réessaie si elle est inachevée et l'ignore une fois traitée. Rendez aussi les effets métier idempotents, car dédupliquer le stockage ne déduplique pas les effets.

Peut-on renvoyer un événement webhook Stripe ?+

Oui. Renvoyez un événement isolé depuis le tableau de bord Stripe ou avec stripe events resend evt_…. Stripe conserve les événements 30 jours : listez-les via l'API pour repérer les écarts. Pour des réparations plus larges, rejouez vos propres événements enregistrés durablement.

Nous contacter
FlowMRR

Écrivez-nous

Une question, un souci technique ou une idée de partenariat ? Échangez avec l'équipe FlowMRR.