Webhooki GitHub: tworzenie, weryfikacja i ponowne wysyłanie
Webhooki GitHub
Webhooki GitHub: konfiguracja, zdarzenia i weryfikacja podpisu | We.Inc
Utwórz webhook GitHub, wybierz zdarzenia, weryfikuj nagłówek X-Hub-Signature-256 działającym kodem i ponów nieudane dostarczenia. Zawiera sprawdzarkę podpisu działającą w przeglądarce.
Webhook GitHub to wiadomość, którą GitHub wysyła na URL Twojego serwera za każdym razem, gdy coś dzieje się w repozytorium, na przykład push, nowe issue lub wydanie. Dodajesz go w Settings repozytorium, w sekcji Webhooks. Ustaw sekret, aby móc sprawdzać nagłówek X-Hub-Signature-256 i odrzucać fałszywe dostarczenia.
Fakty o webhookach GitHub, które warto znać (docs.github.com, październik 2026)
Element
Co podaje dokumentacja GitHub
Nagłówek podpisu
X-Hub-Signature-256, wartość zaczyna się od sha256=
Metoda podpisu
Skrót HMAC w hex z SHA-256, Twój sekret jako klucz
Czas odpowiedzi
Ponad 10 sekund jest zapisywane jako nieudane dostarczenie
Automatyczne ponowienia
Brak. Nieudane dostarczenia nie są automatycznie wysyłane ponownie
Ręczne ponowne wysłanie
Dostarczenia z ostatnich 3 dni
Limit rozmiaru payloadu
25 MB. Większe payloady nie są dostarczane
Webhooki pozwalają GitHubowi informować Twoją stronę lub aplikację o zmianach w chwili, gdy zachodzą, więc możesz przebudować stronę przy każdym pushu, wysłać wiadomość po otwarciu issue lub zaktualizować changelog przy wydaniu. Najważniejsza część, którą pomija większość szybkich poradników, to sprawdzenie, czy dostarczenie naprawdę pochodzi od GitHuba. Poniższa sprawdzarka oblicza ten sam podpis, który wysyła GitHub, bezpośrednio w Twojej przeglądarce.
Otwórz repozytorium, kliknij Settings, potem Webhooks na lewym pasku bocznym, a następnie Add webhook.
Wpisz swój endpoint w polu Payload URL i wybierz application/json jako typ treści, aby treść przychodziła jako zwykły JSON.
W polu Secret wpisz długi losowy ciąg i trzymaj tę samą wartość w zmiennych środowiskowych serwera.
W sekcji Which events would you like to trigger this webhook wybierz samo zdarzenie push lub poszczególne zdarzenia, zaznacz Active i zapisz.
GitHub od razu wysyła zdarzenie ping. Sprawdź je w Recent Deliveries, aby potwierdzić, że Twój serwer odpowiedział.
Odpowiadaj szybko. Zwróć status 2xx niemal od razu, a wolną pracę wykonaj później w zadaniu w tle, bo odpowiedź wolniejsza niż 10 sekund liczy się jako niepowodzenie.
Obliczaj podpis na surowych bajtach treści, przed jakimkolwiek parsowaniem JSON. Parsowanie i ponowna serializacja zmieniają bajty i weryfikacja się nie udaje.
Porównuj podpisy funkcją o stałym czasie, taką jak crypto.timingSafeEqual, nigdy zwykłym porównaniem ==.
Używaj X-GitHub-Delivery, unikalnego ID każdego dostarczenia, aby pomijać duplikaty przy ręcznym ponownym wysyłaniu.
Subskrybuj tylko zdarzenia, które obsługujesz. Mniej zdarzeń to mniej żądań do Twojego serwera i mniej do zabezpieczenia.
Najczęściej zadawane pytania
Czy GitHub ponawia nieudane webhooki?
Nie. Dokumentacja GitHub stwierdza, że nieudane dostarczenia nie są automatycznie wysyłane ponownie. Możesz ręcznie wysłać ponownie dostarczenie z ostatnich 3 dni w Recent Deliveries.
Czym jest nagłówek X-Hub-Signature-256?
Jest wysyłany, gdy webhook ma sekret. GitHub bierze treść żądania, oblicza HMAC z SHA-256, używając Twojego sekretu jako klucza, i wysyła wynik w hex z prefiksem sha256=. Twój serwer powtarza obliczenie i porównuje.
Jakie zdarzenia może odbierać webhook?
Wiele, w tym push, pull_request, issues, release i workflow_run. Nagłówek X-GitHub-Event podaje nazwę zdarzenia, które wywołało dane dostarczenie, a ping przychodzi przy pierwszym utworzeniu hooka.
Czy mogę przetestować webhook bez publicznego serwera?
Twój endpoint musi być dostępny z internetu, bo GitHub wysyła na niego żądania. Przy pracy lokalnej uruchom narzędzie tunelujące, które daje Twojemu komputerowi tymczasowy publiczny URL, i użyj go jako Payload URL.
Webhook czy odpytywanie API?
Webhook przesyła Ci każdą zmianę w chwili, gdy zachodzi, a odpytywanie to pytanie API w regularnych odstępach. Webhooki zużywają mniej żądań i docierają szybciej, co ma znaczenie, bo wywołania API wliczają się do limitów.
Co przychodzi z każdym dostarczeniem
Każde dostarczenie to POST z opisującymi je nagłówkami: X-GitHub-Event podaje nazwę zdarzenia, X-GitHub-Delivery to unikalne ID, X-GitHub-Hook-ID identyfikuje webhook, a User-Agent zawsze zaczyna się od GitHub-Hookshot/.
Treść to payload zdarzenia. Przy pushu zawiera listę commitów i referencję gałęzi, więc skrypt wdrożeniowy może ignorować pushe do gałęzi innych niż ta, którą buduje.
Sprawdzanie kodu weryfikacji na wartościach testowych GitHuba
GitHub publikuje znane dane wejściowe, abyś mógł udowodnić poprawność kodu przed uruchomieniem: sekret It's a Secret to Everybody i payload Hello, World! powinny dać podpis zaczynający się od 757107ea.
Sprawdzarka na tej stronie jest wypełniona tymi wartościami. Jeśli Twój serwer obliczy z nich ten sam wynik, Twój kod weryfikacji jest poprawny.
Ta trasa Express odczytuje surową treść, oblicza HMAC z Twoim sekretem i porównuje go w stałym czasie, zanim zaufa payloadowi.
express.raw zachowuje dokładnie te bajty, które podpisał GitHub. Sekret pochodzi ze zmiennej środowiskowej, nigdy z kodu.
Nagłówki dostarczenia
Nagłówki każdego dostarczenia webhooka GitHub
Nagłówek
Co zawiera
X-GitHub-Event
Nazwę zdarzenia, np. push lub issues
X-GitHub-Delivery
Unikalne ID (GUID) tego dostarczenia
X-GitHub-Hook-ID
ID webhooka, który je wysłał
X-Hub-Signature-256
sha256= i HMAC treści, tylko gdy ustawiono sekret
User-Agent
Zawsze zaczyna się od GitHub-Hookshot/
Sprawdzarka podpisu webhooka
Wpisz sekret i surową treść żądania, aby zobaczyć wartość X-Hub-Signature-256, którą wysłałby GitHub. Działa w Twojej przeglądarce z Web Crypto API, nic nie jest przesyłane.
Sekret webhooka
Surowa treść żądania
Otrzymany nagłówek podpisu (opcjonalnie)
sha256=...
Obliczony podpis
Zgodność: podpis tego dostarczenia jest prawidłowy dla tego sekretu i treści.
Brak zgodności: różnią się sekret, bajty treści lub nagłówek.
Wczytaj wartości testowe GitHuba
Z wartościami testowymi GitHuba wynik powinien wynosić: