GuidesE-commerce
Des webhooks Stripe fiables : signature, doublons, ordre et reprise
Les quatre règles
- 1VérifierLa signature, sur le corps brut, avec le secret du point d’entrée.
- 2DédoublonnerL’identifiant de l’événement est enregistré ; un doublon est ignoré.
- 3Répondre viteUn 200 immédiat ; le travail lourd part en file.
- 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.