Das lokale Testen von GitHub-Webhooks lässt dich Push-, Pull-Request-, Issue- und Workflow-Events auf deiner Maschine empfangen, ohne nach Staging zu deployen. Starte einen localhost-Tunnel, registriere die HTTPS-URL in deinen GitHub-App- oder Repository-Einstellungen und debugge Handler mit voller Signaturprüfung.
Warum GitHub-Webhooks einen öffentlichen Endpunkt brauchen
GitHub liefert Webhook-Events als HTTP-POST-Requests an eine konfigurierte URL. Deine lokale Maschine auf 127.0.0.1 ist von GitHubs Servern nicht erreichbar. Ein localhost-Tunnel liefert den öffentlichen HTTPS-Endpunkt, den GitHub verlangt.
GitHub Apps vs. Repository-Webhooks
Repository-Webhooks
Pro Repository unter Settings → Webhooks konfiguriert. Gut, um die Event-Handler eines einzelnen Repos während der Feature-Entwicklung zu testen.
GitHub-App-Webhooks
Auf App-Ebene in deinen GitHub-App-Einstellungen konfiguriert. Nötig, wenn du Integrationen baust, die mehrere Repositories oder Organisationen bedienen.
Beide Lieferarten nutzen HMAC-SHA256-Signaturprüfung über den X-Hub-Signature-256-Header.
Schritt für Schritt: GitHub-Webhooks lokal testen
- Starte deine lokale App mit einem Webhook-Endpunkt (zum Beispiel
/api/webhooks/github). - Führe
npx portpreview 3000aus, um eine öffentliche HTTPS-URL zu erhalten. - Füge in GitHub die Tunnel-URL plus deinen Webhook-Pfad als Payload-URL hinzu.
- Setze den Content-Type auf
application/jsonund wähle die zu empfangenden Events. - Erzeuge ein Webhook-Secret und lege es in deinen lokalen Umgebungsvariablen ab.
- Löse Events aus (Commit pushen, PR öffnen, Issue erstellen) und inspiziere die Deliveries.
- Prüfe, dass dein Handler die Signatur validiert und innerhalb von 10 Sekunden eine 2xx-Antwort zurückgibt.
GitHub-Webhook-Signaturen lokal verifizieren
GitHub signiert jedes Payload mit deinem Webhook-Secret. Dein Handler muss:
- Den rohen Request-Body vor dem JSON-Parsing lesen.
- HMAC-SHA256 mit deinem Secret berechnen.
- Mit dem
X-Hub-Signature-256-Header per zeitkonstantem Vergleich abgleichen.
Tunnel-Tools, die die Original-Header bewahren, lassen dich den echten Verifizierungspfad testen. Überspringe Signaturprüfungen während der lokalen Entwicklung nie.
Events, die du lokal testen solltest
push— CI-Trigger-Logik, Branch-Protection-Hooks, Deployment-Pipelines.pull_request— Review-Automation, Label-Bots, Merge-Checks.issues— Issue-Tracker-Sync, Zuweisungs-Workflows.installation— GitHub-App-Install-/Uninstall-Lebenszyklus.workflow_run— Post-CI-Automation und Artefakt-Verarbeitung.
Fehlgeschlagene GitHub-Webhook-Deliveries debuggen
GitHub wiederholt fehlgeschlagene Deliveries mit exponentiellem Backoff. Häufige Fehler beim lokalen Testen:
- Handler-Timeout (GitHub erwartet Antwort binnen 10 Sekunden).
- Signatur-Mismatch durch Parsen des Bodys vor der Verifizierung.
- Tunnel-Session abgelaufen, während GitHub wiederholt.
- Falscher Event-Filter — der Handler empfängt Events, die er nicht verarbeitet.
Nutze Webhook-Replay, um fehlgeschlagene Deliveries erneut zu testen, ohne neue Commits zu pushen.
GitHub-Webhook-Testing vs. smee.io
smee.io ist ein beliebter GitHub-Webhook-Proxy für die lokale Entwicklung. Es funktioniert gut für einfaches Weiterleiten, aber es fehlen eingebaute Request-Inspektion und Replay. PortPreview kombiniert Tunneling mit Capture und Replay in einem Tool. Einen breiteren Webhook-Debugging-Leitfaden findest du unter wie man Webhooks lokal debuggt.
Tritt der PortPreview-Warteliste bei für GitHub-Webhook-Testing mit eingebauter Request-Sichtbarkeit.