GitLab Webhooks: Einrichtung, Signing Token und Auto-Deaktivierung | We.Inc
GitLab-Webhook für Projekt oder Gruppe anlegen, Trigger wählen, webhook-signature oder X-Gitlab-Token prüfen und sehen, wann GitLab einen Hook deaktiviert.
Ein GitLab-Webhook sendet einen HTTP POST an deine URL, wenn in einem Projekt oder einer Gruppe etwas passiert, etwa ein Push, ein Merge Request oder ein neuer Kommentar. Du legst ihn unter Einstellungen, Webhooks an. Schütze ihn mit einem Signing Token und antworte schnell mit 200, denn GitLab deaktiviert Hooks, die ständig fehlschlagen.
Fakten zu GitLab-Webhooks (docs.gitlab.com, Oktober 2026)
Punkt
Was GitLab dokumentiert
Wer einen Projekt-Hook anlegen kann
Rolle Maintainer oder Owner
Gruppen-Webhooks
Tarife Premium und Ultimate
Vorübergehende Deaktivierung
Nach 4 aufeinanderfolgenden Fehlern, beginnend bei 1 Minute, ansteigend bis 24 Stunden
Dauerhafte Deaktivierung
Nach 40 aufeinanderfolgenden Fehlern
Timeout auf GitLab.com
10 Sekunden
Hooks pro Projekt / Gruppe auf GitLab.com
Gespeicherte letzte Ereignisse
Requests der letzten zwei Tage
Über Webhooks teilt GitLab deiner Website, deinem Deploy-Skript oder deinem Team-Chat mit, dass sich etwas geändert hat, ohne dass dein Code immer wieder nachfragen muss. Die Einrichtung dauert eine Minute. Ärger machen später zwei Dinge: nachzuweisen, dass ein Request wirklich von GitLab kommt, und zu verhindern, dass der Hook abgeschaltet wird. Die Prüfung unten erzeugt eine Signing-Token-Signatur in deinem Browser, damit du deinen Empfänger testen kannst.
Öffne das Projekt, wähle in der linken Seitenleiste Einstellungen, Webhooks und dann Neuen Webhook hinzufügen.
Trag den Endpunkt unter URL ein, Sonderzeichen dabei prozentkodiert, und füge bei Bedarf Name und Beschreibung hinzu.
Wähle Signing Token generieren und kopiere ihn sofort, GitLab zeigt ihn nur einmal an.
Hake unter Trigger die gewünschten Ereignisse an, etwa Push-Ereignisse oder Merge-Request-Ereignisse, und wähle dann Webhook hinzufügen.
Sende mit der Test-Option eine Beispiel-Zustellung und öffne dann Bearbeiten und Letzte Ereignisse, um den Request und die Antwort deines Servers zu sehen.
Antworte mit 200 oder 201, sobald der Request ankommt, und erledige die eigentliche Arbeit im Hintergrund. Timeouts zählen als Fehler.
Gib 4xx nur zurück, wenn der Hook selbst falsch konfiguriert ist. GitLab wertet jede 4xx- oder 5xx-Antwort als Fehler auf dem Weg zur Deaktivierung.
Nutze den Header webhook-id oder Idempotency-Key, die bei Wiederholungen gleich bleiben, um eine bereits verarbeitete Wiederholung zu ignorieren.
Lehne Zustellungen mit altem webhook-timestamp ab, damit ein abgefangener Request später nicht erneut abgespielt werden kann.
Wurde ein Hook dauerhaft deaktiviert, repariere zuerst den Empfänger und sende dann einen Test-Request, der eine 2xx-Antwort bekommt, um ihn wieder einzuschalten.
Häufige Fragen
Was ist X-Gitlab-Token?
Das ist der ältere geheime Token. Wenn du einen setzt, sendet GitLab ihn als Klartext im Header X-Gitlab-Token und dein Server vergleicht ihn. Die GitLab-Doku empfiehlt für neue Webhooks inzwischen stattdessen einen Signing Token.
Warum wurde mein GitLab-Webhook deaktiviert?
GitLab deaktiviert einen Hook nach vier aufeinanderfolgenden Fehlern, also 4xx- oder 5xx-Antworten, Verbindungs-Timeouts oder anderen HTTP-Fehlern. Zuerst ist er eine Minute aus, mit jedem weiteren Fehler länger bis zu 24 Stunden, und nach 40 in Folge dauerhaft.
Wie erkenne ich, welches Ereignis angekommen ist?
Lies den Header X-Gitlab-Event. Sein Wert ist der Ereignistyp gefolgt von Hook, zum Beispiel Push Hook, Merge Request Hook, Note Hook für Kommentare oder Pipeline Hook.
Kann ich einen Webhook für eine ganze Gruppe anlegen?
Ja, in den Tarifen Premium und Ultimate. Ein Gruppen-Webhook feuert bei Ereignissen in jedem Projekt der Gruppe und kann außerdem Ereignisse zu Gruppenmitgliedern, Projekten und Untergruppen empfangen.
Funktioniert der Signing Token auf selbst verwaltetem GitLab?
Laut GitLab-Doku kam er in Version 19.0 hinter einem standardmäßig aktiven Feature-Flag und wurde in 19.1 allgemein verfügbar. Ältere selbst verwaltete Versionen haben nur den geheimen Token.
So funktioniert der Signing Token
Ein Signing Token beginnt mit whsec_. Entferne dieses Präfix und dekodiere den Rest per Base64, um den Schlüssel zu erhalten. GitLab signiert den String aus webhook-id, einem Punkt, webhook-timestamp, einem Punkt und dem rohen Body mit HMAC-SHA256.
Das Ergebnis wird Base64-kodiert und im Header webhook-signature als v1, gefolgt von der Signatur, gesendet. GitLab folgt der Standard-Webhooks-Spezifikation, daher können auch Bibliotheken für dieses Format die Signatur prüfen.
Ohne Ausfall von einem geheimen Token umsteigen
Ein Hook kann beide Tokens gleichzeitig tragen. Richte den Signing Token ein, stell deinen Empfänger so um, dass er die Signatur prüft, wenn sie vorhanden ist, und sonst auf X-Gitlab-Token zurückfällt, und entferne dann das alte Geheimnis.
Dieser Empfänger prüft die Signing-Token-Signatur, lehnt veraltete Zeitstempel ab und fällt während der Umstellung auf den alten geheimen Token zurück.
Die Tokens kommen aus Umgebungsvariablen. Das Frischefenster von fünf Minuten ist unsere eigene Wahl, nimm, was zu dir passt.
Häufige Ereignisse und ihre X-Gitlab-Event-Werte
GitLab-Webhook-Ereignisse
Ereignis
Header X-Gitlab-Event
Push
Push Hook
Tag-Push
Tag Push Hook
Issue oder Work Item
Issue Hook
Kommentar
Note Hook
Merge Request
Merge Request Hook
Pipeline
Pipeline Hook
Job
Job Hook
Deployment
Deployment Hook
Release
Release Hook
Wiki-Seite
Wiki Page Hook
Signatur-Builder für Signing Tokens
Gib einen Signing Token, die webhook-id, den webhook-timestamp und den rohen Body ein, um den webhook-signature-Wert zu erhalten, den GitLab senden würde. Alles läuft in deinem Browser.
Signing Token (beginnt mit whsec_)
Roher Request-Body
Der Token muss mit whsec_ beginnen, gefolgt von Base64-Text.
Der vorausgefüllte Token ist ein erfundenes Beispiel, kein echter Schlüssel. Mit diesen Werten lautet das Ergebnis: