GuidesE-commerce

Des webhooks Stripe fiables : signature, doublons, ordre et reprise

Par l’équipe Banzai LabsMis à jour le 3 min de lecture

StripeSignatureDéjà traité ?Réponse 200TraitementRenvoyé jusqu’à réceptionVérifier, dédoublonner, répondre vite, traiter ensuite
Chaque événement Stripe est vérifié, dédoublonné, accusé tout de suite, puis traité.

Les quatre règles

  1. 1VérifierLa signature, sur le corps brut, avec le secret du point d’entrée.
  2. 2DédoublonnerL’identifiant de l’événement est enregistré ; un doublon est ignoré.
  3. 3Répondre viteUn 200 immédiat ; le travail lourd part en file.
  4. 4Relire l’étatEn cas de doute sur l’ordre, on interroge l’API Stripe.

Le point d’entrée

export async function POST({ request }: { request: Request }) {
  const brut = await request.text();
  const sig = request.headers.get('stripe-signature')!;
  let event;
  try {
    event = stripe.webhooks.constructEvent(brut, sig, process.env.STRIPE_WEBHOOK_SECRET!);
  } catch {
    return new Response('signature invalide', { status: 400 });
  }
  const nouveau = await db.evenements.insererSiAbsent(event.id); // contrainte unique
  if (nouveau) await file.ajouter(event); // traitement asynchrone
  return new Response('ok');
}

Les pièges

Piège Conséquence Parade
Corps JSON réécrit Signature refusée Lire le texte brut
Traitement long avant la réponse Stripe réessaie, doublons Répondre puis traiter
Pas de contrôle des doublons Commande créée deux fois Identifiant unique en base
Supposer l’ordre des événements État incohérent Relire l’objet via l’API

N’écouter que l’utile

Dans le tableau de bord, abonnez le point d’entrée aux seuls événements traités (checkout.session.completed, invoice.paid, customer.subscription.deleted…).

Avant : Stripe Checkout. Le principe : le webhook.

Questions fréquentes

Pourquoi la vérification de signature échoue-t-elle ?
Presque toujours parce que le corps de la requête a été transformé (JSON analysé puis réécrit) avant la vérification. Il faut le corps brut, octet pour octet.
Que se passe-t-il si mon serveur est en panne ?
Stripe réessaie pendant plusieurs jours avec des délais croissants. Les événements manqués restent consultables dans le tableau de bord.
Comment tester en local ?
Avec la CLI Stripe : stripe listen --forward-to vers votre adresse locale, puis stripe trigger pour déclencher un événement.

À lire ensuite

Tous les guides