Webhook

Webhookは、リアルタイム通知によってGitLabを他のツールやシステムに接続します。GitLabで重要なイベントが発生すると、Webhookはその情報を外部アプリケーションに直接送信します。マージリクエスト、コードプッシュ、イシューの更新に反応して自動化ワークフローをビルドします。

Webhookを使用すると、変更発生時にチームが連携の取れた状態を維持できます:

• GitLabイシューが変更されると、外部イシュートラッカーが自動的に更新されます。
• チャットアプリケーションが、パイプラインの完了をチームメンバーに通知します。
• コードがmainブランチに到達すると、カスタムスクリプトがアプリケーションをデプロイします。
• モニタリングシステムが、組織全体での開発アクティビティーを追跡します。

Webhookイベント

Webhookは、GitLabのさまざまなイベントによってトリガーできます。次に例を示します:

• リポジトリへのコードプッシュ。
• イシューへのコメントの投稿。
• マージリクエストの作成。

Webhookの制限

Webhookの制限には、以下が含まれます: GitLab.com:

• プロジェクトまたはグループごとのWebhookの最大数。
• 1分あたりのWebhook呼び出し数。
• Webhookのタイムアウト期間。

GitLab Self-Managedでは、管理者がこれらの制限を変更できます。

プッシュイベントの制限

GitLabは、複数の変更を含むプッシュイベントのWebhookトリガーを制限します:

• デフォルトの制限: プッシュごとに3つのブランチまたはタグ。
• 超過した場合の動作: プッシュイベント全体でWebhookはトリガーされません。
• 適用対象: プロジェクトWebhookとシステムフックの両方。
• 設定: GitLabセルフマネージドの管理者は、アプリケーション設定APIを使用して、push_event_hooks_limit設定を変更できます。

複数のタグまたはブランチを頻繁に同時にプッシュし、Webhook通知が必要な場合は、GitLab管理者に連絡してこの制限を引き上げてください。

グループWebhook

グループWebhookは、グループとそのサブグループ内のすべてのプロジェクトのイベントに関する通知を送信するカスタムHTTPコールバックです。

グループWebhookイベントの種類

次のイベントをリッスンするようにグループWebhookを設定できます:

• グループとサブグループ内のプロジェクトで発生するすべてのトリガーイベント。
• グループメンバーイベント、プロジェクトイベント、サブグループイベントなど、グループ固有のイベント

プロジェクトとグループの両方のWebhook

グループとそのグループ内のプロジェクトの両方で同一のWebhookを設定すると、そのプロジェクト内のイベントに対して両方のWebhookがトリガーされます。これにより、GitLab組織のさまざまなレベルで柔軟なイベント処理が可能になります。

Webhookを設定する

GitLabでWebhookを作成、設定して、プロジェクトのワークフローと統合します。これらの機能を使用して、特定の要件を満たすWebhookを設定します。

Webhookを作成する

プロジェクトまたはグループ内のイベントに関する通知を送信するWebhookを作成します。

前提要件:

• プロジェクトWebhookの場合、プロジェクトのメンテナー以上のロールを持っている必要があります。
• グループWebhookの場合、グループのオーナーロールを持っている必要があります。

Webhookを作成するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 設定 > Webhooksを選択します。
3. 新しいWebhookを追加を選択します。
4. URLに、WebhookエンドポイントのURLを入力します。特殊文字にはパーセントエンコードを使用します。
5. オプション。Webhookの名前と説明を入力します。
6. オプション。シークレットトークンに、リクエストを検証するためのトークンを入力します。
7. トリガーセクションで、Webhookをトリガーするイベントを選択します。
8. オプション。SSLの検証を有効にするの検証を無効にするには、SSLの検証を有効にするチェックボックスをオフにします。
9. Webhookを追加を選択します。

シークレットトークンは、X-Gitlab-Token HTTPヘッダーのWebhookリクエストとともに送信されます。Webhookエンドポイントは、このトークンを使用してリクエストの正当性を検証できます。

Webhook URLの機密部分をマスクする

セキュリティを強化するため、Webhook URLの機密部分をマスクします。マスクされた部分は、Webhookの実行時に設定された値に置き換えられ、ログに記録されず、データベースでの保存時には暗号化されます。

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

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 設定 > Webhooksを選択します。
3. URLに、Webhookの完全なURLを入力します。
4. マスクする部分を定義するには、Add URL masking（URLマスキングの追加）を選択します。
5. URLの機密部分に、マスクするURLの部分を入力します。
6. UIの外観についてに、マスクされた部分の代わりに表示する値を入力します。変数名には、小文字（a-z）、数字（0-9）、アンダースコア（_）のみを使用する必要があります。
7. 変更を保存を選択します。

マスクされた値はUIでは非表示になります。たとえば、変数pathとvalueを定義した場合、Webhook URLは次のようになります:

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

カスタムヘッダー

外部サービスへの認証のために、カスタムヘッダーをWebhookリクエストに追加します。Webhookごとに最大20個のカスタムヘッダーを設定できます。

カスタムヘッダーは以下の条件を満たしている必要があります:

• ヘッダーの値をオーバーライドしません。
• 英数字、ピリオド、ダッシュ、アンダースコアのみが含まれている。
• 文字で始まり、文字または数字で終わる。
• 連続したピリオド、ダッシュ、またはアンダースコアがない。

カスタムヘッダーは、値がマスクされた状態で最近のイベントに表示されます。

カスタムWebhookテンプレート

リクエスト本文で送信されるデータを制御するWebhookのカスタムペイロードテンプレートを作成します。

カスタムWebhookテンプレートを作成する

• プロジェクトWebhookの場合、プロジェクトのメンテナー以上のロールを持っている必要があります。
• グループWebhookの場合、グループのオーナーロールを持っている必要があります。

カスタムWebhookテンプレートを作成するには、次の手順に従います:

1. Webhookの設定に移動します。
2. カスタムWebhookテンプレートを設定します。
3. テンプレートが有効なJSONとしてレンダリングされることを確認します。

テンプレートで、トリガーイベントのペイロードのフィールドを使用します。次に例を示します:

• {{build_name}}（ジョブイベント）
• {{deployable_url}}（デプロイイベント）

ネストされたプロパティにアクセスするには、ピリオドを使用してパスセグメントを区切ります。

カスタムWebhookテンプレートの例

次のカスタムペイロードテンプレートの場合:

{
  "event": "{{object_kind}}",
  "project_name": "{{project.name}}"
}

その結果作成されるpushイベントのリクエストペイロードは次のようになります:

{
  "event": "push",
  "project_name": "Example"
}

カスタムWebhookテンプレートは、配列内のプロパティにアクセスできません。この機能のサポートは、イシュー463332で提案されています。

ブランチでプッシュイベントをフィルタリングする

Webhookエンドポイントに送信されるpushイベントをブランチ名でフィルタリングします。次のいずれかのフィルタリングオプションを使用します:

• すべてのブランチ: すべてのブランチからプッシュイベントを受信します。
• ワイルドカードパターン: ワイルドカードパターンに一致するブランチからプッシュイベントを受信します。
• 正規表現: 正規表現（regex）に一致するブランチからプッシュイベントを受信します。

ワイルドカードパターンを使用する

ワイルドカードパターンを使用してフィルタリングするには、次の手順に従います:

1. Webhook設定でワイルドカードパターンを選択します。
2. パターンを入力します。次に例を示します:
   • *-stableは、-stableで終わるブランチに一致します。
   • production/*は、production/ネームスペース内のブランチに一致します。

正規表現を使用する

正規表現を使用してフィルタリングするには、次の手順に従います:

1. Webhook設定で正規表現を選択します。
2. RE2構文に従っている正規表現パターンを入力します。

たとえば、mainブランチを除外するには、次を使用します:

\b(?:m(?!ain\b)|ma(?!in\b)|mai(?!n\b)|[a-l]|[n-z])\w*|\b\w{1,3}\b|\W+

相互TLSをサポートするようにWebhookを設定する

PEM形式のグローバルクライアント証明書を設定して、相互TLSをサポートするようにWebhookを設定します。

前提要件:

• GitLab管理者である必要があります。

Webhookの相互TLSを設定するには、次の手順に従います:

1. PEM形式のクライアント証明書を準備します。
2. オプション。PEMパスフレーズで証明書を保護します。
3. 証明書を使用するようにGitLabを設定します。

設定が完了したら、GitLabはWebhook接続のTLSハンドシェイク中にこの証明書をサーバーに提示します。

Webhookトラフィックのファイアウォールを設定する

GitLabがWebhookを送信する方法に基づいて、Webhookトラフィックのファイアウォールを設定します:

• Sidekiqノードから非同期的に送信（最も一般的）
• Railsノードから同期的に送信（特定のケース）

Webhookは、UIでWebhookをテストまたは再試行すると、Railsノードから同期的に送信されます。

ファイアウォールを設定するときには、SidekiqノードとRailsノードの両方がWebhookトラフィックを送信できることを確認してください。

Webhookを管理する

GitLabで設定済みWebhookをモニタリングおよび保守します。

Webhookリクエストの履歴を表示する

Webhookリクエストの履歴を表示して、パフォーマンスをモニタリングし、問題のトラブルシューティングを行います。

前提要件:

• プロジェクトWebhookの場合、プロジェクトのメンテナー以上のロールを持っている必要があります。
• グループWebhookの場合、グループのオーナーロールを持っている必要があります。

Webhookのリクエスト履歴を表示するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 設定 > Webhooksを選択します。
3. Webhookの編集を選択します。
4. 最近のイベントセクションに移動します。

最近のイベントセクションには、過去2日間にWebhookに対して行われたすべてのリクエストが表示されます。テーブルには以下の内容が示されます:

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

リクエストと応答の詳細を調べる

前提要件:

• プロジェクトWebhookの場合、プロジェクトのメンテナー以上のロールを持っている必要があります。
• グループWebhookの場合、グループのオーナーロールを持っている必要があります。

最近のイベントの各Webhookリクエストには、リクエストの詳細ページがあります。このページには、次の本文とヘッダーが含まれています:

• GitLabがWebhookレシーバーエンドポイントから受信した応答
• GitLabが送信したWebhookリクエスト

Webhookイベントのリクエストと応答の詳細を調べるには、次のようにします:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 設定 > Webhooksを選択します。
3. Webhookの編集を選択します。
4. 最近のイベントセクションに移動します。
5. イベントの詳細を表示を選択します。

同じデータと同一のIdempotency-Keyヘッダーを使用してリクエストを再送信するには、リクエストを再送するを選択します。Webhook URLが変更された場合、リクエストを再送信できません。プロジェクトWebhook APIを介して、プログラムでリクエストを再送信することもできます。

Webhookをテストする

Webhookが正しく動作していることを確認するか、無効になっているWebhookを再度有効にするには、テストを実行します。

前提要件:

• プロジェクトWebhookの場合、プロジェクトのメンテナー以上のロールを持っている必要があります。
• グループWebhookの場合、グループのオーナーロールを持っている必要があります。
• push eventsをテストするには、プロジェクトに少なくとも1つのコミットが必要です。

Webhookをテストするには、次のようにします:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 設定 > Webhooksを選択すると、このプロジェクトのすべてのWebhookが表示されます。
3. 構成されたWebhookのリストから直接Webhookをテストするには:
   1. テストするWebhookを見つけます。
   2. テストドロップダウンリストから、テストするイベントの種類を選択します。
4. Webhookの編集中にWebhookをテストするには:
   1. テストするWebhookを見つけて、編集を選択します。
   2. Webhookに変更を加えます。
   3. テストドロップダウンリストから、テストするイベントの種類を選択します。

プロジェクトWebhookとグループWebhookの特定の種類のイベントでは、テストはサポートされていません。詳細については、イシュー379201を参照してください。

Webhookリファレンス

このテクニカルリファレンスは、次の目的で使用します:

• GitLab Webhookの仕組みを理解する。
• システムとWebhookを統合する。
• Webhookの設定、トラブルシューティング、最適化を行う。

Webhookレシーバーの要件

信頼性の高いWebhook配信を確保するために、高速で安定したWebhookレシーバーエンドポイントを実装します。

低速、不安定、または不適切に設定されたWebhookレシーバーは、自動的に無効になることがあります。無効なHTTP応答は、失敗したリクエストとして扱われます。

Webhookレシーバーを最適化するには、次の手順に従います:

1. 200または201のステータスで迅速に応答します:
   • 同じリクエストでWebhookを処理しないでください。
   • 受信後、キューを使用してWebhookを処理します。
   • GitLab.comでの自動無効化を防ぐため、タイムアウト制限より前に応答します。
2. 潜在的な重複イベントを処理します:
   • Webhookがタイムアウトする場合の重複イベントに備えます。
   • エンドポイントが常に高速かつ安定していることを確認します。
3. 応答ヘッダーと本文を最小限に抑える:
   • GitLabは、後で検査するためにリクエストのヘッダーと本文を保存します。
   • 返されるヘッダーの数とサイズを制限します。
   • 空の本文で応答することを検討してください。
4. 適切なステータスコードを使用します:
   • クライアントエラーステータス応答（4xxの範囲）は、誤った設定のWebhookに対してのみ返します。
   • サポートされていないイベントの場合は、400を返すか、ペイロードを無視します。
   • 処理されたイベントに対する500サーバーエラー応答を回避します。

自動的に無効化されたWebhook

GitLabは、4回連続して失敗したプロジェクトまたはグループのWebhookを自動的に無効にします。

自動的に無効になったWebhookを表示するには、次の手順に従います:

1. 左側のサイドバーで、検索または移動先を選択して、プロジェクトまたはグループを見つけます。
2. 設定 > Webhooksを選択します。

Webhookリストでは、自動的に無効になったWebhookは次のように表示されます:

• Webhookは4回連続して失敗すると、一時的に無効になります。
• 40回連続して失敗した場合は無効

一時的に無効化されたWebhook

Webhookは4回連続して失敗すると、一時的に無効になります。Webhookが40回連続して失敗すると、完全に無効になります。

次の場合に失敗が発生します:

• Webhookレシーバーが4xxまたは5xxの範囲の応答リクエストを返した場合。
• WebhookがWebhookレシーバーへの接続を試行中に、タイムアウトが発生した場合。
• Webhookでその他のHTTPエラーが発生した場合。

一時的に無効化されたWebhookは、最初は1分間無効になります。この期間は、後続の失敗発生時に延長され、最大で24時間まで延長されます。この期間が経過すると、これらのWebhookは自動的に再度有効になります。

永久に無効化されたWebhook

Webhookは、40回連続して失敗すると永久に無効になります。一時的に無効になっているWebhookとは異なり、完全に無効になっているWebhookは自動的に再度有効にはなりません。

GitLab 17.10以前に永久に無効化されたWebhookに対してデータ移行が行われました。これらのWebhookは、UIが40件の失敗があると示している場合でも、最近のイベントに4件の失敗が表示されることがあります。

無効化されたWebhookを再度有効にする

無効になっているWebhookを再度有効にするには、テストを送信します。テストリクエストが2xxの範囲の応答コードを返すと、Webhookが再度有効になります。

配信ヘッダー

GitLabは、エンドポイントへのWebhookリクエストに次のヘッダーを含めます:

Webhook本文での画像URLの表示

GitLabは、Webhook本文内の相対的な画像参照を絶対URLに書き換えます。

画像URLの書き換えの例

マージリクエスト、コメント、またはWikiページ内の元の画像参照が次のようであるとします:

![A Markdown image with a relative URL.](/uploads/$sha/image.png)

Webhook本文内で書き換えられた画像参照は次のようになります:

![A Markdown image with an absolute URL.](https://gitlab.example.com/-/project/:id/uploads/<SHA>/image.png)

この例では、以下を前提としています:

• GitLabがgitlab.example.comにインストールされている。
• プロジェクトIDが123にある。

画像URLの書き換えの例外

次の場合、GitLabは画像URLを書き換えません:

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

関連トピック

• WebhookイベントとJSONペイロード
• Webhookの制限
• プロジェクトWebhook API
• グループWebhook API
• システムフックAPI
• Webhookのトラブルシューティング
• WebhookとTwilioでSMSアラートを送信する
• GitLabラベルを自動的に適用する