Rejoindre la waitlist
Tous les articles
Une requête webhook circulant depuis des services cloud vers un ordinateur portable affichant un inspecteur de requêtes.
webhook debuggingStripeGitHublocal testing

Déboguer les webhooks en local : guide complet

Le débogage webhook local doit être rapide, reproductible et proche de la production. Pourtant, beaucoup d'équipes déploient encore en staging pour savoir si le callback est arrivé, si le payload est valide et si la signature passe.

Le problème du test webhook uniquement en staging

Workflow habituel : déployer, configurer l'endpoint, déclencher, lire les logs, corriger, redéployer. Chaque cycle coûte du temps et ajoute du bruit.

Pour valider la logique handler, l'idempotence ou le parsing, cette surcharge est inutile. Il faut déboguer les webhooks en local avec contrôle total de la stack dev.

Ce qu'il faut pour tester les webhooks sur localhost

  • Une app locale avec routes webhook actives.
  • Un endpoint HTTPS public mappé à cette app.
  • Visibilité sur en-têtes, corps, statut et latence.

C'est ce que le tunneling localhost apporte : un pont sécurisé des services externes vers votre processus local.

Étapes : déboguer les webhooks avec PortPreview

  1. Lancez votre app localement.
  2. Exécutez npx portpreview 3000.
  3. Collez l'URL HTTPS dans le dashboard provider (Stripe, GitHub, Twilio…).
  4. Déclenchez des événements test et inspectez chaque callback.
  5. Rejouez les requêtes capturées pour valider vos correctifs.

Bonnes pratiques

Validez les signatures en local. Ne contournez pas la sécurité ; testez le même chemin qu'en production.

Simulez retries et doublons. Les providers peuvent livrer le même événement plusieurs fois.

Réduisez les déploiements staging. Itérez en local, puis validez en staging avant release.

Comparez les outils dans notre guide alternative à ngrok. Rejoignez la waitlist PortPreview.

Checklist webhook par provider

Stripe

Vérifiez routing par type d'événement, clés d'idempotence et validation signature. Voir test webhook Stripe en local.

GitHub

Validez en-têtes de livraison, filtres d'événements et chemins d'autorisation. Voir test webhook GitHub en local.

Twilio

Inspectez payloads form-encoded et timing de réponse. Voir test webhook Twilio en local.

Pour les retries, utilisez rejeu webhook et comparez PortPreview vs localtunnel.

Questions fréquentes

Pourquoi les fournisseurs de webhooks ne peuvent pas joindre localhost ?
Les webhooks transitent par Internet public. Les adresses localhost ne sont joignables que sur votre machine ; les fournisseurs ont besoin d'une URL publique qui redirige vers votre serveur local.
Comment tester les webhooks Stripe en local ?
Lancez votre app, démarrez un tunnel PortPreview, puis configurez l'endpoint webhook Stripe avec l'URL HTTPS générée. Déclenchez des événements test et inspectez chaque livraison.
Puis-je déboguer les webhooks sans déployer en staging ?
Oui. Le débogage webhook local avec un tunnel remplace la plupart des déploiements staging temporaires pour les tests de callbacks.