Comment configurer les webhooks Stripe dans Next.js App Router

Configurer Stripe correctement dans un SaaS Next.js prend rarement moins de 5 heures. Entre la signature du webhook, la gestion idempotente des événements, le mapping plan-prix et la mise à jour atomique des abonnements en base, chaque étape cache un piège. Voici la méthode complète pour le faire proprement avec le App Router.

1. Créer la route webhook

Dans app/api/stripe/webhook/route.ts, exportez un handler POST. La signature doit être vérifiée AVANT de parser le body. Next.js 16 expose request.text() pour récupérer le body brut nécessaire à la vérification.

const sig = request.headers.get('stripe-signature')!
const body = await request.text()
const event = stripe.webhooks.constructEvent(body, sig, process.env.STRIPE_WEBHOOK_SECRET!)

2. Gérer les événements clés

Quatre événements minimum doivent être traités :

• checkout.session.completed — création de l'abonnement ou achat ponctuel
• customer.subscription.updated — synchronisation des changements de plan
• customer.subscription.deleted — marquer l'abonnement comme annulé
• invoice.paid — recharger les crédits mensuels

3. Mapper les Stripe Price IDs aux plans

Stockez les plans dans le code (pas en base). Le webhook fait la correspondance entre line_items[0].price.id et votre configuration. Cela évite les migrations à chaque changement tarifaire.

4. Idempotence et atomicité

Stripe peut réémettre un événement. Conservez l'event.id en base et ignorez les doublons. Pour les crédits, utilisez des RPC SQL (decrement_credits, add_credits) — jamais d'UPDATE direct.

5. Tester en local

Utilisez la CLI Stripe : stripe listen --forward-to localhost:3000/api/stripe/webhook puis stripe trigger customer.subscription.created pour simuler chaque événement.

Conclusion

Les webhooks Stripe sont le pilier de la facturation moderne mais comportent de nombreux pièges. Une fois bien câblés, ils deviennent invisibles. Boilerplate-Stack implémente tout ce flux et bien plus dans un starter kit production-ready.