Pour tester un webhook, vous fournissez au fournisseur une URL accessible, déclenchez un événement réel, puis confirmez que votre gestionnaire accepte la charge utile et réagit correctement. La difficulté est que votre application est le récepteur, et non l'appelant, vous ne pouvez donc pas simplement cliquer sur « Envoyer » et lire la réponse. Ce guide décrit les outils dont vous avez besoin (services d'inspection, tunnels locaux, déclencheurs de fournisseur) et un processus reproductible pour valider votre gestionnaire de bout en bout.
Pourquoi les webhooks sont plus difficiles à tester que les API normales
Avec un appel API normal, vous contrôlez la requête. Vous choisissez la méthode, définissez le corps, l'envoyez et lisez la réponse. Les webhooks inversent cela. Le fournisseur vous envoie la requête, selon son propre calendrier, avec une charge utile qu'il définit. Ce renversement de rôle crée quatre problèmes de test.
Premièrement, vous ne pouvez pas déclencher l'événement vous-même par défaut. Un événement payment_intent.succeeded ne se déclenche que lorsque Stripe le décide, vous avez donc besoin d'outils de fournisseur pour en forcer un.
Deuxièmement, la livraison est asynchrone. L'événement arrive dès que l'action en amont est terminée, votre test doit donc capturer une requête entrante plutôt que d'attendre une valeur de retour.
Troisièmement, la structure de la charge utile est définie par le fournisseur. Votre gestionnaire doit analyser exactement ce que GitHub, Stripe ou Slack envoie.
Quatrièmement, la plupart des fournisseurs signent leurs requêtes. Votre point de terminaison doit vérifier un en-tête de signature avant de faire confiance au corps, et un test qui ignore cela masque de vrais bogues. Pour un examen plus approfondi, consultez notre guide sur la vérification de la signature de webhook.
Si vous n'avez pas encore décidé si les webhooks sont le bon modèle pour votre intégration, webhooks vs polling et webhook vs WebSocket comparent les compromis.
La boîte à outils de test de webhook
Vous utiliserez quatre types d'outils, souvent dans la même session : un service de capture pour voir les charges utiles brutes, un tunnel pour atteindre votre ordinateur portable, des déclencheurs de fournisseur pour lancer de vrais événements, et un outil d'assertion pour vérifier votre gestionnaire.
1. Services d'inspection et de capture
Avant d'écrire une seule ligne de code de gestionnaire, dirigez le fournisseur vers une URL jetable et examinez ce qu'il envoie réellement. Ces services vous donnent un point de terminaison public et affichent chaque requête en temps réel.
webhook.site vous donne une URL et une adresse e-mail uniques et aléatoires dès le chargement de la page. Tout ce qui y est envoyé apparaît instantanément : corps complet, en-têtes et méthode. Les URL gratuites expirent après 7 jours et sont limitées à 100 requêtes, avec une taille de requête maximale de 10 Mo. Les plans payants ajoutent des URL permanentes, des requêtes illimitées et un historique conservé des 10 000 dernières requêtes.
Beeceptor propose un point de terminaison HTTPS gratuit que vous pouvez utiliser comme récepteur de webhook et inspecter les charges utiles entrantes en temps réel. Il fournit également des points de terminaison de serveur de maquette, afin que vous puissiez capturer et simuler à partir du même outil.
Pipedream RequestBin est un autre outil de capture de requêtes largement utilisé. Consultez sa documentation actuelle pour les spécificités des niveaux, car les services de capture modifient souvent leurs limites gratuites.
Utilisez-les pour répondre à une question : à quoi ressemble la vraie charge utile ? Copiez un échantillon pour plus tard, lorsque vous créerez des tests reproductibles.
2. Développement local : exposer localhost avec un tunnel
Les fournisseurs ne peuvent pas atteindre localhost:3000 sur votre machine. Un tunnel crée une URL HTTPS publique qui transfère le trafic vers votre port local, vous permettant ainsi d'exécuter votre gestionnaire dans votre éditeur et de le déboguer en direct.
ngrok est le choix courant. Installez-le, authentifiez-vous une fois, puis transférez un port.
brew install ngrok # macOS
ngrok config add-authtoken $YOUR_TOKEN
ngrok http 3000 # transfère une URL HTTPS publique vers localhost:3000
Les comptes ngrok gratuits obtiennent un domaine de développement choisi automatiquement. Les domaines personnalisés nécessitent un forfait payant.
cloudflared exécute un tunnel rapide avec une seule commande si vous préférez Cloudflare.
cloudflared tunnel --url http://localhost:3000
Collez l'URL publique affichée par le tunnel dans les paramètres de webhook du fournisseur, et les événements entrants arriveront sur votre serveur local. Pour une présentation plus complète de ce modèle, consultez comment tester les API localhost avec des services de webhook.
3. Déclenchement d'événements de test depuis le fournisseur
Une URL de capture n'est utile que lorsque quelque chose y est envoyé. La plupart des principaux fournisseurs proposent des outils pour déclencher des événements de test à la demande, vous n'avez donc pas à créer de vrais paiements ou de poussées.
La CLI Stripe est l'exemple le plus clair. La commande stripe listen transmet les événements en direct de votre sandbox Stripe à un chemin local, et elle affiche un secret de signature de webhook que vous placez dans la configuration de votre application.
# Transférer tous les événements à votre gestionnaire local :
stripe listen --forward-to localhost:3000/webhooks
# Filtrer pour des événements spécifiques uniquement :
stripe listen --events payment_intent.succeeded,checkout.session.completed \
--forward-to localhost:3000/webhooks
Avec l'écouteur en cours d'exécution, stripe trigger déclenche un événement de test. Notez que le déclenchement crée des objets API correctement pris en charge et a des effets secondaires : payment_intent.succeeded émet également payment_intent.created.
stripe trigger payment_intent.succeeded
stripe trigger checkout.session.completed
stripe trigger --help # lister tous les événements pris en charge
GitHub conserve un court historique de livraison que vous pouvez rejouer. Allez dans votre dépôt, puis Paramètres, puis Webhooks sous « Code et automatisation ». Cliquez sur l'URL du webhook, ouvrez l'onglet « Livraisons récentes », cliquez sur un GUID de livraison, et cliquez sur « Relivrer ». Deux contraintes sont importantes : vous ne pouvez relivrer que les livraisons des 3 derniers jours, et vous avez besoin d'un accès administrateur au dépôt. GitHub ne relivre pas automatiquement les livraisons échouées, la relecture est donc manuelle.
Les webhooks entrants de Slack sont les plus simples à tester. Vous envoyez un message en envoyant du JSON par POST à l'URL du webhook. La charge utile minimale est simplement un champ text.
curl -X POST https://hooks.slack.com/services/T00000000/B00000000/XXXXXXXXXXXXXXXXXXXXXXXX \
-H 'Content-type: application/json' \
-d '{"text":"Hello, world."}'
L'URL du webhook Slack est un secret. Slack révoque les URL qui fuient, alors gardez-la hors du code côté client et des dépôts publics.
4. Assertion de votre gestionnaire
Capturer et déclencher prouvent que la plomberie fonctionne. Ils ne prouvent pas que votre gestionnaire est correct. L'outil final envoie une charge utile élaborée et vérifie la réponse ainsi que les effets secondaires. À la base, il s'agit d'une commande curl avec un corps représentatif.
curl -X POST http://localhost:3000/webhooks \
-H 'Content-Type: application/json' \
-H 'Stripe-Signature: t=...,v1=...' \
-d '{"id":"evt_test","type":"payment_intent.succeeded","data":{"object":{"id":"pi_123","status":"succeeded"}}}'
Un simple curl convient pour un test de fumée. Il est insuffisant lorsque vous voulez des tests reproductibles et assertifs qui s'exécutent en CI. C'est là qu'un outil API dédié prend tout son sens.
Tester les webhooks avec Apidog
Apidog est une plateforme API tout-en-un pour la conception, le débogage, le test, la simulation et la documentation des API. Il n'a pas de « boîte de réception de webhook » dédiée, cette section est donc honnête sur ce qu'il fait réellement bien : créer des charges utiles, les enregistrer, affirmer les réponses et remplacer un fournisseur avec un serveur de maquette.
Créer et enregistrer une charge utile d'exemple comme requête réutilisable
Prenez la charge utile que vous avez capturée depuis webhook.site (ou copiée depuis la documentation d'un fournisseur) et intégrez-la dans une requête Apidog. Définissez la méthode sur POST, collez le corps JSON et ajoutez les en-têtes envoyés par le fournisseur, y compris l'en-tête de signature que votre gestionnaire vérifie.
Enregistrez cette requête pour votre point de terminaison. Vous disposez maintenant d'un moyen reproductible et contrôlé par version d'envoyer une charge utile valide (ou délibérément mal formée) à votre gestionnaire, au lieu de retaper une commande curl à chaque fois.Assertir la réponse avec le constructeur d'assertions visuel
L'envoi de la charge utile est la moitié du test. L'autre moitié consiste à vérifier ce que votre gestionnaire renvoie. Dans l'étape de requête ou de scénario, ouvrez Post Processors, cliquez sur « + Ajouter » et choisissez « Assertion ». Apidog ajoute une règle de validation que vous configurez sans code.
Dirigez l'assertion vers le corps de la réponse et utilisez $ pour la racine JSON. Par exemple, ciblez $.data.status, définissez la condition sur "Égal à" et comparez à succeeded. Exécutez la requête, et le résultat s'affiche dans l'onglet Assertion. Les assertions visuelles comparent les valeurs comme des chaînes de caractères. Lorsque vous avez besoin de vérifications précises de type (un nombre réel, un booléen), passez à un script personnalisé utilisant la syntaxe pm.test compatible avec Postman.
Cela transforme « il a renvoyé un 200 » en « il a renvoyé un 200, le champ d'état est réussi, et l'identifiant de commande correspond ». Intégrez plusieurs assertions dans un seul scénario pour couvrir le chemin de succès, un cas de champ manquant et un rejet de mauvaise signature.
Utiliser un serveur de maquette pour remplacer le fournisseur
Parfois, vous voulez tester l'autre direction : un service dans votre pile qui appelle un fournisseur. Lors des tests locaux, vous ne voulez peut-être pas du tout contacter le vrai fournisseur. Le serveur de maquette d'Apidog vous permet de le remplacer.
Apidog propose trois types de maquettes. La maquette locale (Local Mock) s'exécute avec le client de bureau et ne fonctionne que lorsque le client est ouvert. La maquette Cloud (Cloud Mock) est hébergée sur les serveurs Apidog, fonctionne 24h/24 et 7j/7, et s'active ou se désactive (elle est désactivée par défaut). La maquette Runner (Runner Mock) s'exécute sur une infrastructure de runner auto-hébergée et est partagée par votre équipe. Chaque point de terminaison HTTP dispose d'un module de maquette ; copiez l'URL de la maquette depuis l'onglet API en mode Design ou l'onglet Mock en mode Debug. Seuls les chemins commençant par / sont acheminés vers l'environnement de maquette. Pointez votre code vers cette URL de maquette pendant les tests, et votre intégration obtiendra des réponses de fournisseur prévisibles sans appels API réels ni effets secondaires.
Exécuter des tests de webhook en CI avec la CLI Apidog
Une fois que votre scénario passe localement, exécutez-le à chaque push avec la CLI Apidog. Il nécessite Node.js v16 ou ultérieur.
npm install -g apidog-cli
node -v && apidog -v && which node && which npm && which apidog # vérifier l'installation
Exécutez un scénario enregistré en ligne, en transmettant le jeton d'accès et les identifiants depuis l'onglet « Ligne de commande » CI/CD du scénario.
apidog run --access-token $APIDOG_ACCESS_TOKEN -t 637132 -e 358171 -d 3497013 -r html,cli
Ici, -t est le scénario de test, -e est l'environnement (obligatoire), -d sont les données de test (un chemin de fichier CSV ou JSON, ou un ID de jeu de données stocké), et -r définit les rapporteurs, qui acceptent cli, html, json et junit. Pour une présentation complète de la ligne de commande, consultez le tutoriel de la CLI Apidog.
Vous voulez créer et affirmer vos propres tests de webhook visuellement ? Essayez Apidog gratuitement, aucune carte de crédit requise.
Un flux de travail de test de webhook étape par étape
En combinant les outils, voici une séquence reproductible.
- Inspectez la charge utile réelle. Dirigez le fournisseur vers une URL webhook.site et capturez un événement réel. Notez la structure du corps, les en-têtes et le format de la signature.
- Atteignez votre code. Démarrez votre gestionnaire localement, ouvrez un tunnel avec
ngrok http 3000oucloudflared, et insérez l'URL publique dans la configuration du webhook du fournisseur. - Déclenchez un événement réel. Utilisez
stripe trigger, le bouton Redeliver de GitHub ou un POST Slack pour envoyer un événement authentique via le tunnel. - Vérifiez la gestion des signatures. Envoyez la même charge utile avec une signature valide et une autre altérée. Votre gestionnaire doit accepter la première et rejeter la seconde.
- Assertissez la réponse et les effets secondaires. Enregistrez la charge utile comme une requête Apidog, ajoutez des assertions sur le corps et l'état de la réponse, et confirmez que la ligne de la base de données ou l'appel en aval a eu lieu.
- Automatisez-le. Déplacez le scénario dans la CLI Apidog pour qu'il s'exécute en CI à chaque changement.
Si vous concevez le système de webhook lui-même plutôt que d'en consommer un, comment concevoir des webhooks fiables et les meilleures pratiques de webhook de paiement couvrent les tentatives, l'idempotence et la sécurité. Pour une vue d'ensemble, le guide de l'API webhooks et les webhooks et l'architecture événementielle expliquent où les webhooks s'inscrivent dans un système plus vaste.
Questions Fréquemment Posées
Comment tester un webhook ?
Fournissez au fournisseur une URL accessible, déclenchez un événement réel ou de test, puis confirmez que votre gestionnaire reçoit la charge utile, vérifie la signature, renvoie le statut correct et produit l'effet secondaire attendu. Capturez d'abord une charge utile réelle, puis construisez une requête reproductible avec des assertions afin que le test s'exécute de la même manière à chaque fois.
Comment tester les webhooks localement ?
Exécutez votre gestionnaire sur un port local, puis exposez-le avec un tunnel afin que le fournisseur puisse atteindre votre machine. Utilisez ngrok http 3000 ou cloudflared tunnel --url http://localhost:3000, collez l'URL HTTPS publique dans les paramètres de webhook du fournisseur et déclenchez un événement. Les requêtes entrantes arrivent sur votre serveur local, où vous pouvez définir des points d'arrêt et les inspecter en direct.
Comment tester un webhook avec Postman ?
Postman peut envoyer une charge utile élaborée à votre point de terminaison et affirmer la réponse, mais il ne peut pas recevoir un véritable webhook entrant par lui-même. Il en va de même pour Apidog : vous construisez une requête avec la charge utile et les en-têtes du fournisseur, ajoutez des assertions sur le corps et le statut de la réponse, et l'enregistrez comme un test réutilisable. Pour capturer un événement entrant authentique, associez l'outil à un service de capture ou à un tunnel.
Comment tester les webhooks Stripe ?
Utilisez la CLI Stripe. Exécutez stripe listen --forward-to localhost:3000/webhooks pour transférer les événements de sandbox à votre gestionnaire et obtenir un secret de signature. Ensuite, exécutez stripe trigger payment_intent.succeeded (ou tout événement de stripe trigger --help) pour déclencher un événement de test réel. Le déclenchement crée des objets API pris en charge et peut cascader, de sorte que payment_intent.succeeded émet également payment_intent.created.
Comment tester un webhook Slack ?
Envoyez du JSON par POST à l'URL du webhook entrant. La charge utile valide minimale est {"text":"Hello, world."}, envoyée avec un en-tête Content-type: application/json. Un test réussi publie le message dans le canal configuré. Gardez l'URL secrète, car Slack révoque les URL de webhook qui fuient.
Comment tester une URL de webhook ?
Envoyez un échantillon POST à l'URL et confirmez qu'il renvoie un statut de succès et se comporte correctement. La vérification la plus rapide est un simple curl avec un corps représentatif. Pour un test réel, capturez d'abord une charge utile réelle, envoyez-la avec des signatures valides et invalides, et affirmez la réponse et les effets secondaires plutôt que de simplement vérifier un statut 200.