Webhooki GitLab: konfiguracja, weryfikacja i błędy
Webhooki GitLab
Webhooki GitLab: konfiguracja, signing token i automatyczne wyłączanie | We.Inc
Dodaj webhook projektu lub grupy w GitLab, wybierz zdarzenia, weryfikuj nagłówek webhook-signature lub X-Gitlab-Token i sprawdź, kiedy GitLab wyłącza hook.
Webhook GitLab wysyła żądanie HTTP POST na Twój URL, gdy w projekcie lub grupie zajdzie zdarzenie, na przykład push, merge request lub nowy komentarz. Dodasz go w Settings, Webhooks. Zabezpiecz go signing tokenem i odpowiadaj szybko kodem 200, bo GitLab wyłącza hooki, które ciągle zawodzą.
Fakty o webhookach GitLab (docs.gitlab.com, październik 2026)
Element
Co podaje dokumentacja GitLab
Kto może dodać hook projektu
Rola Maintainer lub Owner
Webhooki grupy
Plany Premium i Ultimate
Tymczasowe wyłączenie
Po 4 kolejnych niepowodzeniach, początkowo na 1 minutę, wydłużane do 24 godzin
Trwałe wyłączenie
Po 40 kolejnych niepowodzeniach
Limit czasu na GitLab.com
10 sekund
Hooki na projekt / grupę na GitLab.com
Przechowywane ostatnie zdarzenia
Żądania z ostatnich dwóch dni
Webhooki to sposób, w jaki GitLab informuje Twoją stronę, skrypt wdrożeniowy lub czat zespołu, że coś się zmieniło, bez ciągłego odpytywania przez Twój kod. Konfiguracja zajmuje minutę. Problemy pojawiają się później: trzeba udowodnić, że żądanie przyszło z GitLab, i nie dopuścić do wyłączenia hooka. Poniższa sprawdzarka tworzy w Twojej przeglądarce podpis signing tokena, abyś mógł przetestować swój odbiornik.
Otwórz projekt, a następnie na lewym pasku bocznym wybierz Settings, Webhooks i kliknij Add new webhook.
Wpisz endpoint w polu URL, kodując znaki specjalne procentowo, i jeśli chcesz, dodaj Name i Description.
Wybierz Generate signing token i od razu go skopiuj. GitLab wyświetla go tylko raz.
W sekcji Trigger zaznacz potrzebne zdarzenia, takie jak push events lub merge request events, a następnie wybierz Add webhook.
Użyj opcji Test, aby wysłać przykładowe dostarczenie, a potem otwórz Edit i Recent events, aby zobaczyć żądanie i odpowiedź Twojego serwera.
Odpowiadaj kodem 200 lub 201 zaraz po nadejściu żądania, a właściwą pracę wykonuj w tle. Przekroczenia limitu czasu liczą się jako niepowodzenia.
Zwracaj 4xx tylko wtedy, gdy sam hook jest źle skonfigurowany. GitLab traktuje każdą odpowiedź 4xx lub 5xx jako niepowodzenie zbliżające wyłączenie.
Używaj nagłówka webhook-id lub Idempotency-Key, które nie zmieniają się przy ponowieniach, aby ignorować ponowienie, które już przetworzyłeś.
Odrzucaj dostarczenia ze starym webhook-timestamp, aby przechwyconego żądania nie dało się później odtworzyć.
Jeśli hook został trwale wyłączony, najpierw napraw odbiornik, a potem wyślij żądanie testowe, które dostanie odpowiedź 2xx, aby go ponownie włączyć.
Najczęściej zadawane pytania
Czym jest X-Gitlab-Token?
To starszy tajny token. Gdy go ustawisz, GitLab wysyła go jawnym tekstem w nagłówku X-Gitlab-Token, a Twój serwer go porównuje. Dokumentacja GitLab zaleca teraz dla nowych webhooków signing token.
Dlaczego mój webhook GitLab został wyłączony?
GitLab wyłącza hook po czterech kolejnych niepowodzeniach, czyli odpowiedziach 4xx lub 5xx, przekroczeniach limitu czasu połączenia lub innych błędach HTTP. Najpierw jest wyłączony na minutę, przy każdym kolejnym niepowodzeniu dłużej, do 24 godzin, a trwale po 40 z rzędu.
Jak rozpoznać, które zdarzenie nadeszło?
Odczytaj nagłówek X-Gitlab-Event. Jego wartość to typ zdarzenia ze słowem Hook na końcu, na przykład Push Hook, Merge Request Hook, Note Hook dla komentarzy lub Pipeline Hook.
Czy mogę dodać webhook do całej grupy?
Tak, w planach Premium i Ultimate. Webhook grupy uruchamia się przy zdarzeniach w każdym projekcie grupy i może też odbierać zdarzenia członków grupy, projektów i podgrup.
Czy signing token działa w GitLab self-managed?
Dokumentacja GitLab mówi, że pojawił się w wersji 19.0 za flagą funkcji domyślnie włączoną i stał się ogólnie dostępny w 19.1. Starsze wersje self-managed mają tylko tajny token.
Jak działa signing token
Signing token zaczyna się od whsec_. Usuń ten prefiks i zdekoduj resztę z base64, aby uzyskać klucz. GitLab podpisuje algorytmem HMAC-SHA256 ciąg złożony z webhook-id, kropki, webhook-timestamp, kropki i surowej treści żądania.
Wynik jest kodowany w base64 i wysyłany w nagłówku webhook-signature jako v1, a po nim podpis. GitLab stosuje specyfikację Standard Webhooks, więc biblioteki napisane dla tego formatu też mogą go weryfikować.
Przejście z tajnego tokena bez przestoju
Hook może mieć oba tokeny jednocześnie. Skonfiguruj signing token, zmień odbiornik tak, by sprawdzał podpis, gdy jest obecny, a w przeciwnym razie korzystał z X-Gitlab-Token, a następnie usuń stary sekret.
Ten odbiornik sprawdza podpis signing tokena, odrzuca nieaktualne znaczniki czasu i na czas migracji korzysta zapasowo ze starego tajnego tokena.
Tokeny pochodzą ze zmiennych środowiskowych. Pięciominutowe okno ważności to nasz własny wybór, ustaw to, co Ci odpowiada.
Częste zdarzenia i ich wartości X-Gitlab-Event
Zdarzenia webhooków GitLab
Zdarzenie
Nagłówek X-Gitlab-Event
Push
Push Hook
Push tagu
Tag Push Hook
Issue lub work item
Issue Hook
Komentarz
Note Hook
Merge request
Merge Request Hook
Pipeline
Pipeline Hook
Job
Job Hook
Wdrożenie
Deployment Hook
Wydanie
Release Hook
Strona wiki
Wiki Page Hook
Kreator podpisu signing tokena
Wpisz signing token, webhook-id, webhook-timestamp i surową treść żądania, aby uzyskać wartość webhook-signature, którą wysłałby GitLab. Wszystko działa w Twojej przeglądarce.
Signing token (zaczyna się od whsec_)
Surowa treść żądania
Token musi zaczynać się od whsec_, a po nim tekst w base64.
Wstępnie wpisany token to zmyślony przykład, a nie prawdziwy klucz. Z tymi wartościami wynik to:
Kiedy GitLab wyłącza hook?
Kolejne nieudane dostarczenia: {n}
Aktywny: dostarczenia trwają.
Tymczasowo wyłączony: najpierw na 1 minutę, po każdym kolejnym niepowodzeniu dłużej, do 24 godzin, potem automatycznie włączany ponownie.
Trwale wyłączony: pozostaje wyłączony, dopóki żądanie testowe nie dostanie odpowiedzi 2xx.