• グループのWebhook
• GitLab で Webhook を設定します。
• Webhook URL の機密部分をマスクします。
• Webhook 受信エンドポイントの設定
• 失敗した Webhook
  • 無効になった Webhook を再度有効にします。
• Webhook のテスト
• Webhook レシーバーの例を作成します。
• シークレットトークンを使ったペイロードの検証
• ブランチによるプッシュイベントのフィルタリング
• 画像の URL が Webhook 本文に表示される方法
• イベント
• 配信ヘッダ
• ウェブフックの開発者
  • 公開 Webhook 検査・テストツール
  • GitLab 開発キット(GDK)
  • GitLab設定で最近トリガーされたWebhookペイロード
• トラブルシューティング
  • ローカルの発行者証明書を取得できません
  • Webhook が失敗する、または複数の Webhook リクエストがトリガーされる場合
  • Webhookが起動しない

ウェブフック

Webhookは、あなたが定義したカスタム HTTP コールバックです。通常は、リポジトリへのコードのプッシュやイシューへのコメントの投稿などのイベントがトリガーとなります。イベントが発生すると、ソースアプリは Webhook に設定された URI に HTTP リクエストを行います。実行するアクションは何でもかまいません。例えば、Webhook を使って次のようなことができます：

• 継続的インテグレーション(CI) ジョブのトリガー、内部イシュー・トラッカーの更新、バックアップ・ミラーの更新、本番サーバーへのデプロイなどです。
• ジョブが失敗するたびにSlackに通知を送信します。
• Twilioとインテグレーションして、GitLabで特定のプロジェクトやグループにイシューが作成されるたびにSMSで通知。
• マージリクエストに自動的にラベルを割り当てます。

GitLabのプロジェクトやグループでは、イベントが発生したときにパーセントエンコードされたWebhook URLをトリガーするように設定することができます。例えば、新しいコードがプッシュされた時や新しいイシューが作成された時などです。Webhookは特定のイベントをリッスンし、GitLabはWebhook URLにデータを含むPOSTリクエストを送信します。

通常、GitLabから情報を受信して別のアプリに送信するために、要件に応じて独自のWebhookレシーバーを設定します。プロジェクトごとにSlackの通知を送るためのレシーバーが組み込まれています。

GitLab.comは以下のようなWebhookの制限を実施しています：

• プロジェクトごと、グループごとの Webhook の最大数とサイズ。
• 1分あたりのWebhook呼び出し数。

グループのWebhook

グループ Webhook を設定することができます。グループ Webhook は、グループとそのサブグループ内のすべてのプロジェクトで発生したイベントによってトリガーされます。グループとプロジェクトに同じ Webhook を設定した場合、どちらもプロジェクト内のイベントによってトリガーされます。

グループ Webhook は、グループ固有のイベントをリッスンするように設定することもできます：

• グループメンバーのイベント
• サブグループのイベント

GitLab で Webhook を設定します。

プロジェクトやグループの Webhook を設定するには、次のようにします：

1. プロジェクトまたはグループの左サイドバーで、[設定] > [Webhooks]を選択します。
2. 新しいWebhookを追加]を選択します。
3. URL] に Webhook エンドポイントの URL を入力します。URLに1つ以上の特殊文字が含まれている場合は、パーセントエンコードする必要があります。
4. シークレットトークンには、ペイロードを検証するためのシークレットトークンを入力します。
5. Triggerセクションで、Webhook をトリガーするイベントを選択します。
6. オプション。SSL検証を無効にするには、[SSL検証を有効にする]チェックボックスをオフにします。
7. Add Webhookを選択します。

Webhook URL の機密部分をマスクします。

• GitLab 15.5 でwebhook_form_mask_url というフラグで導入されました。デフォルトでは無効です。
• GitLab15.6でGitLab.comで有効に。
• GitLab 15.7で一般的に利用可能に。機能フラグwebhook_form_mask_url を削除しました。

Webhook URL のセンシティブな部分を定義してマスクし、Webhook が実行されるときに何度でも設定された値に置き換えることができます。機密部分はログに記録されず、データベースで暗号化されます。

Webhook URL の機密部分をマスクするには、以下の手順に従います：

1. プロジェクトまたはグループの左サイドバーで、[設定] > [Webhooks]を選択します。
2. URLに、完全なWebhook URLを入力します。
3. URLのマスク部分を選択します。
4. URLの機密部分]に、マスクしたい部分を入力します。
5. UIでの見え方］に、マスキングの値を入力します。

各 Webhook の機密部分を補間するには、url_variablesを使用します。例えば、Webhook が以下の URL の場合：

https://{subdomain}.example.com/{path}?key={value}

以下の変数を定義する必要があります：

• subdomain
• path
• value

変数名には、小文字 (a-z)、数字 (0-9)、またはアンダースコア (_) のみを使用できます。URL 変数は、REST API を使用して直接定義できます。

Webhook 受信エンドポイントの設定

Webhook レシーバーのエンドポイントは、高速で安定している必要があります。低速で不安定なレシーバーは、システムの信頼性を確保するために自動的に無効にすることができます。Webhook が失敗すると、イベントが重複する可能性があります。

エンドポイントは、以下のベストプラクティスに従ってください：

• ** 200 または201 ステータスレスポンスで迅速に応答します。** 同じリクエストで Webhook を大量に処理することは避けてください。代わりに、Webhook を受信した後に処理するキューを実装してください。GitLab.com の Webhook のタイムアウト制限は10 秒です。
• 重複イベントを処理する準備をしておきましょう。 状況によっては、同じイベントが二度送信されることがあります。このイシューを軽減するには、エンドポイントが確実に高速で安定していることを確認してください。
• レスポンスヘッダとボディは最小限にしましょう。 GitLabはレスポンスヘッダやボディを調べません。GitLab はそれらを保存するので、後でログを調べて問題を診断するのに役立ちます。返されるヘッダの数やサイズは制限しましょう。Webhook リクエストに空のボディで応答することもできます。
• Webhook が誤って設定されたことを示すクライアントエラーステータスレスポンス (4xx の範囲) のみを返します。この範囲のレスポンスは、Webhook が自動的に無効になる可能性があります。例えば、レシーバーがプッシュイベントのみをサポートしている場合、イシューペイロードが送信されたら400 を返します。また、認識できないイベントペイロードは無視することもできます。
• イベントが処理された場合、Webhook が一時的に無効になる可能性があるため、500 サーバーエラーステータスレスポンスを返さないでください。
• 無効な HTTP レスポンスは失敗したリクエストとして扱われます。

失敗した Webhook

• GitLab 13.12でプロジェクトのWebhookに導入された web_hooks_disable_failed というフラグ。デフォルトでは無効になっています。
• GitLab 15.7のプロジェクトWebhookで一般的に利用可能。機能フラグweb_hooks_disable_failed を削除しました。
• GitLab 15.10でグループのWebhookに導入。
• GitLab 15.10でauto_disabling_web_hooks というフラグでセルフマネージドを無効に。

フラグ: セルフマネージドGitLabでは、デフォルトではこの機能は利用できません。利用可能にするには、管理者がauto_disabling_web_hooks という機能フラグを有効にします。GitLab.comでは、この機能は利用可能です。

4回連続で失敗したプロジェクトやグループのWebhookは自動的に無効になります。

5xx の範囲のレスポンスコードを返すプロジェクトまたはグループの Webhook は、断続的に失敗していると見なされ、一時的に無効になります。これらの Webhook は最初に 1 分間無効化され、その後失敗するたびに最大 24 時間まで延長されます。

4xx の範囲のレスポンスコードを返すプロジェクトまたはグループの Webhook は設定ミスと見なされ、手動でWebhook を再度有効にするまで永久に無効になります。

無効になった Webhook を再度有効にします。

• GitLab 15.2 でwebhooks_failed_callout というフラグで導入されました。デフォルトでは無効になっています。
• GitLab 15.7で一般的に利用可能に。機能フラグwebhooks_failed_callout を削除しました。

Webhook が失敗している場合、編集ページの上部にバナーが表示され、Webhook が無効になっている理由と自動的に再有効化されるタイミングが説明されます。例えば

Webhook が失敗した場合、エラーバナーが表示されます：

失敗した Webhook または失敗した Webhook を再度有効にするには、テスト要求を送信します。テストリクエストに成功すると、Webhook が再度有効になります。

Webhook のテスト

手動で Webhook を起動し、正常に動作していることを確認できます。また、無効になっている Webhook を再度有効にするためのテストリクエストを送信することもできます。

例えば、push events をテストするには、プロジェクトに少なくとも1つのコミットが必要です。Webhook ではこのコミットを使用します。

前提条件：

• プロジェクトのWebhookをテストするには、少なくともプロジェクトのメンテナーのロールを持っている必要があります。
• グループの Webhook をテストするには、グループのオーナーロールが必要です。

Webhook をテストするには：

1. プロジェクトまたはグループの左サイドバーで、[設定] > [Webhooks]を選択します。
2. 設定されたWebhookのリストまでスクロールダウンします。
3. Testドロップダウンリストから、テストするイベントの種類を選択します。

Webhookの編集ページからテストすることもできます。

Webhook レシーバーの例を作成します。

GitLab Webhook がどのように動作するかをテストするには、コンソールセッションで実行する echo スクリプトを使います。以下のスクリプトを動かすには、Ruby がインストールされている必要があります。

1. 以下のファイルをprint_http_body.rb という名前で保存します：

   require 'webrick'
      
   server = WEBrick::HTTPServer.new(:Port => ARGV.first)
   server.mount_proc '/' do |req, res|
     puts req.body
   end
      
   trap 'INT' do
     server.shutdown
   end
   server.start
   

2. 未使用のポート（例えば、8000 ）を選択し、スクリプトを開始します：

   ruby print_http_body.rb 8000
   

3. GitLab でWebhook を設定し、レシーバーの URL を追加します (例:http://receiver.example.com:8000/)。

4. Test を選択します。コンソールにこのようなものが表示されるはずです：

   {"before":"077a85dd266e6f3573ef7e9ef8ce3343ad659c4e","after":"95cd4a99e93bc4bbabacfa2cd10e6725b1403c60",<SNIP>}
   example.com - - [14/May/2014:07:45:26 EDT] "POST / HTTP/1.1" 200 0
   - -> /
   

シークレットトークンを使ったペイロードの検証

受信したペイロードを検証するためにシークレットトークンを指定することができます。トークンはX-Gitlab-Token HTTP ヘッダーのフックリクエストと共に送信されます。Webhook エンドポイントはこのトークンをチェックすることで、リクエストが正当なものであることを確認できます。

ブランチによるプッシュイベントのフィルタリング

ブランチ別にプッシュイベントをフィルタリングできます。以下のオプションのいずれかを使用して、Webhook エンドポイントに送信されるプッシュイベントをフィルタリングします：

• すべてのブランチ：すべてのブランチからのプッシュイベント。
• ワイルドカードパターン：ワイルドカードパターン（例えば、*-stable やproduction/*）にマッチするブランチからイベントをプッシュします。
• 正規表現：正規表現にマッチするブランチからイベントをプッシュします（例：^(feature|hotfix)/ ）。

プロジェクトやグループのブランチフィルタリングを設定するには、GitLab で Webhook を設定する を参照してください。

画像の URL が Webhook 本文に表示される方法

相対画像参照は、Webhook 本文で絶対 URL を使用するように書き換えられます。例えば、画像、マージリクエスト、コメント、Wikiページに以下の画像参照が含まれている場合：

![image](/uploads/$sha/image.png)

If:

• GitLab がgitlab.example.com にインストールされている場合。
• プロジェクトはexample-group/example-project にあります。

リファレンスは Webhook 本文で以下のように書き換えられます：

![image](https://gitlab.example.com/example-group/example-project/uploads/$sha/image.png)

以下の場合、画像URLは書き換えられません：

• すでにHTTP、HTTPS、またはプロトコル関連のURLを指している場合。
• リンクラベルのような高度なMarkdown機能を使用しています。

イベント

Webhook でサポートされているイベントの詳細については、Webhook イベントを参照してください。

配信ヘッダ

• X-Gitlab-Event-UUID ヘッダは GitLab 14.8 で導入されました。
• X-Gitlab-Instance ヘッダは GitLab 15.5 で導入されました。
• X-Gitlab-Webhook-UUID ヘッダは GitLab 16.2 で導入されました。

エンドポイントへの Webhook リクエストには以下のヘッダが含まれます：

ウェブフックの開発者

Webhook セットアップ用の既存の HTTPS エンドポイントまたは URL がない場合は、サーバー上にデプロイする必要があります。このHTTPSエンドポイントは設定に使用されます。GitLab Webhookに対して開発し、ペイロードをキャプチャするには、以下を使います：

• 公開Webhook検査・テストツール
• GitLab 開発キット(GDK)
• GitLab設定で最近トリガーされたWebhookペイロード

公開 Webhook 検査・テストツール

公開ツールを使って Webhook ペイロードを検査したりテストしたりすることができます。これらのツールは HTTP リクエストのキャッチオールエンドポイントとして動作し、200 OK HTTP ステータスコードで応答します。これらのペイロードを使用して、Webhook サービスを開発することができます。

外部ツールに機密データを送信する可能性があるため、これらのツールを使用する際には注意が必要です。これらのツールでテストトークンを使用し、不注意に第三者に送信されたシークレットをローテートする必要があります。

これらの公開ツールには以下が含まれます：

• 一時的なHTTPSエンドポイントを作成し、受信ペイロードを検査するBeeceptor
• Webhook.siteによる受信ペイロードのレビュー
• 受信ペイロードの検査とデバッグを行うWebhook Tester

GitLab 開発キット(GDK)

より安全な開発環境のために、GitLab Development Kit(GDK)を使って、GitLab Webhookに対して内部で開発することができます。GDKを使えば、ローカルのGitLabインスタンスからあなたのマシン上でローカルに動いているWebhookレシーバーにWebhookを送ることができます。この方法を使うには、GDKをインストールして設定する必要があります。

GitLab設定で最近トリガーされたWebhookペイロード

GitLabの設定で、最近トリガーされたWebhookペイロードをレビューすることができます。各Webhookイベントには、GitLabがWebhookエンドポイントから送受信したデータに関する情報を含む詳細ページが存在します。

トラブルシューティング

GitLab 15.3で導入されたグループWebhookの最近のイベント。

GitLab は各 Webhook リクエストの履歴を記録します。最近のイベントのテーブルで、過去2日間に行われたリクエストを見ることができます。

前提条件：

• プロジェクトのWebhookをトラブルシューティングするには、少なくともプロジェクトのメンテナーのロールを持っている必要があります。
• グループの Webhook をトラブルシューティングするには、グループのオーナーロールが必要です。

テーブルを表示するには

1. プロジェクトまたはグループの左サイドバーで、[設定] > [Webhooks]を選択します。
2. Webhooksまでスクロールダウンします。

3. 失敗したWebhookにはバッジが表示されます：

   • 接続に失敗した場合、手動で再度有効にする必要があります。
   • 一時的に無効になっている場合は接続に失敗し、タイムアウト制限の経過後に自動的に再有効化されます。

   

4. 表示したい Webhook の [編集] を選択します。

表には、各リクエストに関する以下の詳細が表示されます：

• HTTP ステータスコード (200-299 コードは緑、その他は赤、配送に失敗した場合はinternal error )
• トリガーイベント
• リクエストの経過時間
• リクエストが行われた相対時間

各 Webhook イベントには対応する詳細ページがあります。このPagesはGitLabが送信したデータ（リクエストヘッダとボディ）と受信したデータ（レスポンスヘッダとボディ）の詳細を表示します。詳細ページを見るには、Webhookイベントの詳細を見るを選択します。

同じデータで配信を繰り返すには、リクエストの再送を選択します。

ローカルの発行者証明書を取得できません

SSL検証が有効になっている場合、GitLabがWebhookエンドポイントのSSL証明書を検証できないというエラーが表示されることがあります。通常、このエラーはルート証明書がCAcert.orgによって決定された信頼できる認証局によって発行されていないために発生します。

そうでない場合は、SSL Checkerを使用して障害を特定することを検討してください。中間証明書の欠落は、検証失敗の一般的な原因です。

Webhook が失敗する、または複数の Webhook リクエストがトリガーされる場合

複数の Webhook リクエストを受信している場合は、Webhook がタイムアウトしている可能性があります。

GitLabは10秒以内のレスポンスを期待しています。セルフマネジメントのGitLabインスタンスでは、Webhookのタイムアウト制限を変更することができます。

Webhookが起動しない

GitLab 16.3で導入されたサイレントモードではWebhookがトリガーされません。

Webhook がトリガーされない場合は、それを確認してください：

• Webhook が自動的に無効になっていないか確認してください。
• GitLab インスタンスがサイレントモードになっていません。