Rejoindre la waitlist
Tous les articles
Stripewebhook debugginglocal testingpayments

Tester les webhooks Stripe en local : guide complet

Le test webhook Stripe en local permet de valider vos handlers d'événements de paiement sur votre machine avant la production. Vous exposez votre app via une URL HTTPS publique et recevez des événements test-mode avec vérification de signature intacte.

Pourquoi Stripe a besoin d'une URL publique

Stripe livre les webhooks via Internet vers un endpoint configuré. Les adresses 127.0.0.1 sont injoignables — un tunnel localhost mappe une URL HTTPS publique vers votre processus local sans modification routeur.

Prérequis avant de tester

  • Un compte Stripe en mode test.
  • Une app locale avec route webhook (ex. /api/webhooks/stripe).
  • Le secret de signature webhook configuré en variable d'environnement.
  • Un outil tunnel qui préserve les en-têtes pour la vérification de signature.

Étapes : test webhook Stripe avec PortPreview

  1. Lancez votre application localement.
  2. Exécutez npx portpreview 3000 pour obtenir une URL HTTPS publique.
  3. Dans Stripe Dashboard → Webhooks, ajoutez l'URL tunnel et votre chemin webhook.
  4. Sélectionnez les événements à tester (checkout.session.completed, invoice.paid…).
  5. Déclenchez des événements test et inspectez chaque livraison.
  6. Vérifiez que votre handler retourne 2xx et que la validation de signature passe.

Valider les signatures Stripe en local

Ne désactivez jamais la vérification de signature. Votre handler doit valider l'en-tête Stripe-Signature comme en production. Les échecs courants : mauvais secret, corps JSON parsé avant vérification, décalage d'horloge.

Stripe CLI vs tunnel localhost

Le CLI Stripe (stripe listen) convient aux checks rapides. Un tunnel offre une URL stable pour le Dashboard, le partage d'équipe et les tests multi-providers qui reflètent la configuration production.

Quand passer du local au staging

Le test local couvre la logique handler et la validation de signature. Passez en staging pour les secrets managés et les pipelines de release. Guide complet : déboguer les webhooks en local. Rejoignez la waitlist PortPreview.

Événements Stripe à tester

Priorisez checkout.session.completed, abonnements, échecs de paiement et flux Connect. Utilisez le rejeu webhook pour valider l'idempotence sans re-déclencher Stripe.

Questions fréquentes

Comment tester les webhooks Stripe sur localhost ?
Lancez votre app, démarrez un tunnel PortPreview pour obtenir une URL HTTPS publique, puis ajoutez cette URL comme endpoint webhook dans le Dashboard Stripe.
La vérification de signature Stripe fonctionne-t-elle avec un tunnel ?
Oui, si le tunnel préserve les en-têtes et le corps originaux. PortPreview transmet les en-têtes intacts pour que la validation Stripe-Signature fonctionne comme en production.
Stripe CLI ou tunnel localhost ?
Le CLI Stripe est rapide pour le debug solo. Un tunnel localhost offre une URL publique stable pour la configuration Dashboard, le partage d'équipe et les tests multi-providers.