Le test webhook GitHub en local permet de recevoir push, pull request, issues et workflow events sur votre machine sans déployer en staging. Un tunnel localhost, une URL HTTPS enregistrée, et vous déboguez avec vérification HMAC complète.
Pourquoi GitHub a besoin d'un endpoint public
GitHub livre les webhooks en POST HTTP vers une URL configurée. 127.0.0.1 est injoignable. Un tunnel localhost fournit l'endpoint HTTPS requis.
Webhooks repo vs GitHub Apps
Webhooks repo : configurés par dépôt (Settings → Webhooks). Idéal pour tester un repo pendant le développement.
GitHub Apps : configurés au niveau app. Requis pour intégrations multi-repos ou organisations.
Les deux utilisent HMAC-SHA256 via X-Hub-Signature-256.
Étapes : test webhook GitHub
- Lancez votre app avec endpoint webhook (
/api/webhooks/github). - Exécutez
npx portpreview 3000. - Ajoutez l'URL tunnel + chemin dans GitHub.
- Content-type
application/json, sélectionnez les événements. - Générez un secret webhook en variable d'environnement.
- Déclenchez push, PR ou issue et inspectez les livraisons.
- Vérifiez signature et réponse 2xx en moins de 10 secondes.
Valider les signatures GitHub en local
Lisez le corps brut avant parsing JSON. Calculez HMAC-SHA256 avec votre secret. Comparez X-Hub-Signature-256 en temps constant. Ne contournez jamais la vérification en dev.
Événements à tester
push, pull_request, issues, installation, workflow_run — selon votre intégration.
Debug livraisons échouées
Timeout handler (>10s), mismatch signature, session tunnel expirée, mauvais filtre d'événements. Utilisez le rejeu webhook pour re-tester sans nouveaux commits. Guide complet : déboguer les webhooks en local.
Rejoignez la waitlist PortPreview.
GitHub webhook testing vs smee.io
smee.io est un proxy webhook populaire pour le dev local. Il forward bien le trafic mais manque d'inspection intégrée et de rejeu. PortPreview combine tunneling, capture et rejeu dans un seul outil.