GitLabのプロジェクトやグループにWebhookを追加し、トリガーを選び、webhook-signatureヘッダーやX-Gitlab-Tokenを検証する方法と、失敗が続くフックが無効化される条件を解説します。
GitLabのWebhookは、プッシュ、マージリクエスト、新しいコメントなど、プロジェクトやグループでイベントが発生したときに、あなたのURLへHTTP POSTを送信します。「設定」の「Webhook」から追加できます。署名トークンで保護し、200ですばやく応答しましょう。GitLabは失敗が続くフックを無効化するためです。
GitLab Webhookの基本情報（docs.gitlab.com、2026年10月）
Webhookは、あなたのコードが何度も問い合わせなくても、GitLabがサイト、デプロイスクリプト、チームのチャットに変更を知らせる仕組みです。設定は1分で済みます。後で問題になりやすいのは、リクエストが本当にGitLabから来たことを証明する部分と、フックが無効化されないようにする部分です。下のチェッカーはブラウザー内で署名トークンの署名を生成するので、受信側のテストに使えます。
以前からあるシークレットトークンです。設定すると、GitLabはX-Gitlab-Tokenヘッダーにプレーンテキストで入れて送信し、あなたのサーバーがそれを照合します。現在のGitLabのドキュメントでは、新しいWebhookには代わりに署名トークンを使うよう推奨しています。
GitLabは、4回連続で失敗したフックを無効化します。失敗とは、4xxや5xxの応答、接続のタイムアウト、その他のHTTPエラーです。最初は1分間停止し、失敗が重なるたびに最長24時間まで延び、40回連続で失敗すると恒久的に無効化されます。
X-Gitlab-Eventヘッダーを読みます。値はイベントの種類の後にHookが付いたもので、例えばPush Hook、Merge Request Hook、コメントの場合はNote Hook、Pipeline Hookなどです。
はい、PremiumとUltimateのティアで可能です。グループWebhookはグループ内のすべてのプロジェクトのイベントで発火し、グループメンバー、プロジェクト、サブグループのイベントも受け取れます。
GitLabのドキュメントによると、バージョン19.0でデフォルト有効の機能フラグ付きで導入され、19.1で一般提供されました。それより古いセルフマネージド版にはシークレットトークンしかありません。
この受信側は署名トークンの署名を検証し、古いタイムスタンプを拒否し、移行中は古いシークレットトークンでの確認にフォールバックします。
トークンは環境変数から読み込みます。5分間の有効期間は私たちが独自に決めたものなので、用途に合わせて選んでください。
GitLab Webhookのイベント
署名トークン、webhook-id、webhook-timestamp、生のボディを入力すると、GitLabが送信するwebhook-signatureの値を生成します。すべてブラウザー内で処理されます。
署名トークン（whsec_で始まる）
生のリクエストボディ
トークンはwhsec_で始まり、その後にbase64のテキストが続く必要があります。
入力済みのトークンは架空の例で、本物のキーではありません。これらの値での結果は次のとおりです：
GitLabはいつフックを無効化しますか？
連続した配信失敗の回数：{n}
有効：配信は継続されます。
一時的に無効：最初は1分間停止し、失敗が重なるたびに最長24時間まで延びた後、自動的に再有効化されます。
恒久的に無効：テストリクエストで2xxの応答が返るまで停止したままです。
無料で始める · クレジットカード不要