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ć:

Zbuduj stronę za darmo · Za darmo, bez karty

Powiązane: Poradniki

Produkt

Dla kogo

Funkcje

Zasoby

Firma

Mapa strony