Testowanie webhooków GitHub lokalnie: pełny przewodnik

Lokalne testowanie webhooków GitHub pozwala odbierać zdarzenia push, pull request, issue i workflow na twojej maszynie bez wdrażania na staging. Uruchom tunel localhost, zarejestruj URL HTTPS w ustawieniach swojej GitHub App lub repozytorium i debuguj handlery z pełną weryfikacją podpisu.

Dlaczego webhooki GitHub potrzebują publicznego endpointu

GitHub dostarcza zdarzenia webhooków jako żądania HTTP POST na skonfigurowany URL. Twoja lokalna maszyna na 127.0.0.1 jest nieosiągalna z serwerów GitHuba. Tunel localhost zapewnia publiczny endpoint HTTPS, którego wymaga GitHub.

GitHub Apps vs webhooki repozytorium

Webhooki repozytorium

Konfigurowane per repozytorium w Settings → Webhooks. Dobre do testowania handlerów zdarzeń jednego repo podczas tworzenia funkcji.

Webhooki GitHub App

Konfigurowane na poziomie aplikacji w ustawieniach twojej GitHub App. Wymagane przy budowie integracji obsługujących wiele repozytoriów lub organizacji.

Oba typy dostawy używają weryfikacji podpisu HMAC-SHA256 przez nagłówek X-Hub-Signature-256.

Krok po kroku: lokalne testowanie webhooków GitHub

1. Uruchom lokalną aplikację z endpointem webhooka (na przykład /api/webhooks/github).
2. Wykonaj npx portpreview 3000, by uzyskać publiczny URL HTTPS.
3. W GitHubie dodaj URL tunelu plus ścieżkę webhooka jako payload URL.
4. Ustaw content type na application/json i wybierz zdarzenia do odbioru.
5. Wygeneruj sekret webhooka i zapisz go w lokalnych zmiennych środowiskowych.
6. Wyzwól zdarzenia (zrób push commita, otwórz PR, utwórz issue) i sprawdź dostawy.
7. Zweryfikuj, że handler waliduje podpis i zwraca odpowiedź 2xx w ciągu 10 sekund.

Weryfikacja podpisów webhooków GitHub lokalnie

GitHub podpisuje każdy payload twoim sekretem webhooka. Twój handler musi:

• Odczytać surowe ciało żądania przed parsowaniem JSON.
• Obliczyć HMAC-SHA256 używając twojego sekretu.
• Porównać z nagłówkiem X-Hub-Signature-256 używając porównania o stałym czasie.

Narzędzia tunelujące zachowujące oryginalne nagłówki pozwalają testować prawdziwą ścieżkę weryfikacji. Nigdy nie pomijaj sprawdzania podpisu podczas lokalnego developmentu.

Zdarzenia do testowania lokalnie

• push — logika wyzwalania CI, hooki ochrony gałęzi, pipeline'y wdrożeń.
• pull_request — automatyzacja review, boty etykiet, sprawdzenia merge.
• issues — synchronizacja trackera issue, przepływy przypisań.
• installation — cykl życia instalacji/odinstalowania GitHub App.
• workflow_run — automatyzacja po CI i przetwarzanie artefaktów.

Debugowanie nieudanych dostaw webhooków GitHub

GitHub ponawia nieudane dostawy z wykładniczym backoffem. Częste awarie przy lokalnym testowaniu:

• Timeout handlera (GitHub oczekuje odpowiedzi w ciągu 10 sekund).
• Niezgodność podpisu z parsowania ciała przed weryfikacją.
• Sesja tunelu wygasła, gdy GitHub ponawia.
• Zły filtr zdarzeń — handler odbiera zdarzenia, których nie przetwarza.

Użyj powtarzania webhooków, by ponownie przetestować nieudane dostawy bez pushowania nowych commitów.

Testowanie webhooków GitHub vs smee.io

smee.io to popularny proxy webhooków GitHub do lokalnego developmentu. Działa dobrze przy podstawowym przekazywaniu, ale brakuje mu wbudowanej inspekcji żądań i powtarzania. PortPreview łączy tunelowanie z przechwytywaniem i powtarzaniem w jednym narzędziu. Szerszy przewodnik po debugowaniu webhooków zobacz w jak debugować webhooki lokalnie.

Dołącz do listy oczekujących PortPreview po testowanie webhooków GitHub z wbudowaną widocznością żądań.