GitLab-webhooks: instellen, verifiëren en storingen
GitLab-webhooks
GitLab-webhooks: instellen, signing token en automatisch uitschakelen | We.Inc
Voeg een GitLab-webhook toe aan een project of groep, kies triggers, verifieer de webhook-signature-header of X-Gitlab-Token en zie wanneer GitLab een falende hook uitschakelt.
Een GitLab-webhook stuurt een HTTP POST naar uw URL wanneer er iets gebeurt in een project of groep, zoals een push, een merge request of een nieuwe opmerking. U voegt er een toe onder Settings, Webhooks. Beveilig hem met een signing token en antwoord snel met 200, want GitLab schakelt hooks uit die blijven falen.
Feiten over GitLab-webhooks (docs.gitlab.com, oktober 2026)
Onderdeel
Wat GitLab documenteert
Wie een projecthook mag toevoegen
Rol Maintainer of Owner
Groepswebhooks
Abonnementen Premium en Ultimate
Tijdelijk uitschakelen
Na 4 opeenvolgende fouten, eerst 1 minuut, oplopend tot 24 uur
Permanent uitschakelen
Na 40 opeenvolgende fouten
Time-out op GitLab.com
10 seconden
Hooks per project / groep op GitLab.com
Bewaarde recente events
Verzoeken van de afgelopen twee dagen
Met webhooks laat GitLab uw site, deployscript of teamchat weten dat er iets veranderd is, zonder dat uw code steeds opnieuw hoeft te vragen. Instellen kost een minuut; wat later problemen geeft, is bewijzen dat een verzoek echt van GitLab komt en voorkomen dat de hook wordt uitgeschakeld. De checker hieronder maakt een signing token-handtekening in uw browser, zodat u uw ontvanger kunt testen.
Open het project, kies in de linkerzijbalk Settings, Webhooks en selecteer Add new webhook.
Vul het endpoint in onder URL, met procentcodering voor speciale tekens, en voeg desgewenst een Name en Description toe.
Selecteer Generate signing token en kopieer hem meteen; GitLab toont hem maar één keer.
Vink onder Trigger de gewenste events aan, zoals push events of merge request events, en selecteer Add webhook.
Gebruik de optie Test om een voorbeeldlevering te sturen en open daarna Edit en Recent events om het verzoek en het antwoord van uw server te zien.
Antwoord met 200 of 201 zodra het verzoek binnenkomt en doe het echte werk op de achtergrond. Time-outs tellen als fouten.
Geef alleen 4xx terug als de hook zelf verkeerd is ingesteld. GitLab telt elk 4xx- of 5xx-antwoord als fout richting uitschakelen.
Gebruik de header webhook-id of Idempotency-Key, die bij nieuwe pogingen gelijk blijven, om een herhaling te negeren die u al hebt verwerkt.
Weiger leveringen met een oude webhook-timestamp, zodat een onderschept verzoek later niet opnieuw kan worden afgespeeld.
Is een hook permanent uitgeschakeld, herstel dan eerst de ontvanger en stuur daarna een testverzoek dat een 2xx-antwoord krijgt om hem weer aan te zetten.
Veelgestelde vragen
Wat is X-Gitlab-Token?
Dat is de oudere secret token. Stelt u er een in, dan stuurt GitLab hem als platte tekst in de header X-Gitlab-Token en vergelijkt uw server hem. De documentatie van GitLab raadt voor nieuwe webhooks nu een signing token aan.
Waarom is mijn GitLab-webhook uitgeschakeld?
GitLab schakelt een hook uit na vier opeenvolgende fouten, dus 4xx- of 5xx-antwoorden, time-outs bij het verbinden of andere HTTP-fouten. Eerst staat hij één minuut uit, bij elke volgende fout langer tot 24 uur, en permanent na 40 op rij.
Hoe zie ik welk event binnenkwam?
Lees de header X-Gitlab-Event. De waarde is het type event gevolgd door Hook, bijvoorbeeld Push Hook, Merge Request Hook, Note Hook voor opmerkingen of Pipeline Hook.
Kan ik een webhook aan een hele groep toevoegen?
Ja, in de abonnementen Premium en Ultimate. Een groepswebhook gaat af bij events in elk project van de groep en kan ook events over groepsleden, projecten en subgroepen ontvangen.
Werkt de signing token op self-managed GitLab?
Volgens de documentatie van GitLab kwam hij in versie 19.0 achter een feature flag die standaard aan stond, en werd hij algemeen beschikbaar in 19.1. Oudere self-managed versies hebben alleen de secret token.
Hoe de signing token werkt
Een signing token begint met whsec_. Haal dat voorvoegsel weg en decodeer de rest met base64 om de sleutel te krijgen. GitLab ondertekent de string die bestaat uit de webhook-id, een punt, de webhook-timestamp, een punt en de ruwe body, met HMAC-SHA256.
Het resultaat wordt met base64 gecodeerd en in de header webhook-signature verstuurd als v1, gevolgd door de handtekening. GitLab volgt de Standard Webhooks-specificatie, dus bibliotheken voor dat formaat kunnen hem ook verifiëren.
Overstappen van een secret token zonder downtime
Een hook kan beide tokens tegelijk hebben. Stel de signing token in, laat uw ontvanger de handtekening controleren als die aanwezig is en terugvallen op X-Gitlab-Token als dat niet zo is, en verwijder daarna de oude secret.
Deze ontvanger controleert de handtekening van de signing token, weigert verouderde timestamps en valt tijdens de migratie terug op de oude secret token.
Tokens komen uit omgevingsvariabelen. Het venster van vijf minuten is onze eigen keuze; kies wat bij u past.
Veelvoorkomende events en hun X-Gitlab-Event-waarden
Events van GitLab-webhooks
Event
Header X-Gitlab-Event
Push
Push Hook
Tag-push
Tag Push Hook
Issue of work item
Issue Hook
Opmerking
Note Hook
Merge request
Merge Request Hook
Pipeline
Pipeline Hook
Job
Job Hook
Deployment
Deployment Hook
Release
Release Hook
Wikipagina
Wiki Page Hook
Handtekening maken met een signing token
Vul een signing token, de webhook-id, de webhook-timestamp en de ruwe body in om de webhook-signature-waarde te krijgen die GitLab zou sturen. Alles draait in uw browser.
Signing token (begint met whsec_)
Ruwe body van het verzoek
De token moet beginnen met whsec_ gevolgd door base64-tekst.
De vooraf ingevulde token is een verzonnen voorbeeld, geen echte sleutel. Met deze waarden is het resultaat:
Wanneer schakelt GitLab een hook uit?
Opeenvolgende mislukte leveringen: {n}
Actief: leveringen gaan door.
Tijdelijk uitgeschakeld: eerst 1 minuut uit, na elke volgende fout langer, tot 24 uur, daarna automatisch weer aan.
Permanent uitgeschakeld: hij blijft uit tot een testverzoek een 2xx-antwoord krijgt.