正式なドキュメントは英語版であり、この日本語訳はAI支援翻訳により作成された参考用のものです。日本語訳の一部の内容は人間によるレビューがまだ行われていないため、翻訳のタイミングにより英語版との間に差異が生じることがあります。最新かつ正確な情報については、英語版をご参照ください。

プロジェクトWebhook API

  • プラン: Free、Premium、Ultimate
  • 提供形態: GitLab.com、GitLab Self-Managed、GitLab Dedicated

このAPIを使用して、project webhooksを管理します。プロジェクトのWebhookは、インスタンス全体に影響を与えるsystem hooks 、およびグループ内のすべてのプロジェクトとサブグループに影響を与えるgroup webhooksとは異なります。

前提要件:

  • 管理者であるか、プロジェクトのメンテナーロールを持っている必要があります。

プロジェクトのWebhookを一覧表示します

プロジェクトのWebhookのリストを取得します。

GET /projects/:id/hooks

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。

プロジェクトのWebhookを取得します

プロジェクトの特定のWebhookを取得します。

GET /projects/:id/hooks/:hook_id

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。

レスポンス例:

{
  "id": 1,
  "url": "http://example.com/hook",
  "name": "Hook name",
  "description": "Hook description",
  "project_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "issues_events": true,
  "confidential_issues_events": true,
  "merge_requests_events": true,
  "tag_push_events": true,
  "note_events": true,
  "confidential_note_events": true,
  "job_events": true,
  "pipeline_events": true,
  "wiki_page_events": true,
  "deployment_events": true,
  "releases_events": true,
  "milestone_events": true,
  "feature_flag_events": true,
  "enable_ssl_verification": true,
  "repository_update_events": false,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [ ],
  "created_at": "2012-10-12T17:04:47Z",
  "resource_access_token_events": true,
  "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
  "custom_headers": [
    {
      "key": "Authorization"
    }
  ]
}

プロジェクトのWebhookイベントのリストを取得します

特定のプロジェクトのWebhookの過去7日間のイベントのリストを開始日から取得します。

GET /projects/:id/hooks/:hook_id/events

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
status整数または文字列いいえイベントのレスポンスステータスコード。例：200または500。ステータスカテゴリで検索できます: successful（200～299）、client_failure（400～499）、およびserver_failure（500～599）。
page整数いいえ取得するページ。1がデフォルトです。
per_page整数いいえページごとに返すレコード数。20がデフォルトです。

レスポンス例:

[
  {
    "id": 1,
    "url": "https://example.net/",
    "trigger": "push_hooks",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "GitLab/17.1.0-pre",
      "Idempotency-Key": "3a427872-00df-429c-9bc9-a9475de2efe4",
      "X-Gitlab-Event": "Push Hook",
      "X-Gitlab-Webhook-UUID": "3c5c0404-c866-44bc-a5f6-452bb1bfc76e",
      "X-Gitlab-Instance": "https://gitlab.example.com",
      "X-Gitlab-Event-UUID": "9cebe914-4827-408f-b014-cfa23a47a35f",
      "X-Gitlab-Token": "[REDACTED]"
    },
    "request_data": {
      "object_kind": "push",
      "event_name": "push",
      "before": "468abc807a2b2572f43e72c743b76cee6db24025",
      "after": "f15b32277d2c55c6c595845a87109b09c913c556",
      "ref": "refs/heads/master",
      "ref_protected": true,
      "checkout_sha": "f15b32277d2c55c6c595845a87109b09c913c556",
      "message": null,
      "user_id": 1,
      "user_name": "Administrator",
      "user_username": "root",
      "user_email": null,
      "user_avatar": "https://www.gravatar.com/avatar/13efe0d4559475ba84ecc802061febbdea6e224fcbffd7ec7da9cd431845299c?s=80&d=identicon",
      "project_id": 7,
      "project": {
        "id": 7,
        "name": "Flight",
        "description": "Incidunt ea ab officia a veniam.",
        "web_url": "https://gitlab.example.com/flightjs/Flight",
        "avatar_url": null,
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "namespace": "Flightjs",
        "visibility_level": 10,
        "path_with_namespace": "flightjs/Flight",
        "default_branch": "master",
        "ci_config_path": null,
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "http_url": "https://gitlab.example.com/flightjs/Flight.git"
      },
      "commits": [
        {
          "id": "f15b32277d2c55c6c595845a87109b09c913c556",
          "message": "v1.5.2\n",
          "title": "v1.5.2",
          "timestamp": "2017-06-19T14:39:53-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/f15b32277d2c55c6c595845a87109b09c913c556",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "message": "Merge pull request #378 from flightjs/alunny/publish_lib\n\npublish lib and index to npm",
          "title": "Merge pull request #378 from flightjs/alunny/publish_lib",
          "timestamp": "2017-06-16T10:26:39-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "author": {
            "name": "angus croll",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "468abc807a2b2572f43e72c743b76cee6db24025",
          "message": "publish lib and index to npm\n",
          "title": "publish lib and index to npm",
          "timestamp": "2017-06-16T10:23:04-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/468abc807a2b2572f43e72c743b76cee6db24025",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        }
      ],
      "total_commits_count": 3,
      "push_options": {},
      "repository": {
        "name": "Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "description": "Incidunt ea ab officia a veniam.",
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "visibility_level": 10
      }
    },
    "response_headers": {
      "Date": "Sun, 26 May 2024 03:03:17 GMT",
      "Content-Type": "application/json; charset=utf-8",
      "Content-Length": "16",
      "Connection": "close",
      "X-Powered-By": "Express",
      "Access-Control-Allow-Origin": "*",
      "X-Pd-Status": "sent to primary"
    },
    "response_body": "{\"success\":true}",
    "execution_duration": 1.0906479999999874,
    "response_status": "200"
  },
  {
    "id": 2,
    "url": "https://example.net/",
    "trigger": "push_hooks",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "GitLab/17.1.0-pre",
      "Idempotency-Key": "7c6e0583-49f2-4dc5-a50b-4c0bcf3c1b27",
      "X-Gitlab-Event": "Push Hook",
      "X-Gitlab-Webhook-UUID": "a753eedb-1d72-4549-9ca7-eac8ea8e50dd",
      "X-Gitlab-Instance": "https://gitlab.example.com",
      "X-Gitlab-Event-UUID": "842d7c3e-3114-4396-8a95-66c084d53cb1",
      "X-Gitlab-Token": "[REDACTED]"
    },
    "request_data": {
      "object_kind": "push",
      "event_name": "push",
      "before": "468abc807a2b2572f43e72c743b76cee6db24025",
      "after": "f15b32277d2c55c6c595845a87109b09c913c556",
      "ref": "refs/heads/master",
      "ref_protected": true,
      "checkout_sha": "f15b32277d2c55c6c595845a87109b09c913c556",
      "message": null,
      "user_id": 1,
      "user_name": "Administrator",
      "user_username": "root",
      "user_email": null,
      "user_avatar": "https://www.gravatar.com/avatar/13efe0d4559475ba84ecc802061febbdea6e224fcbffd7ec7da9cd431845299c?s=80&d=identicon",
      "project_id": 7,
      "project": {
        "id": 7,
        "name": "Flight",
        "description": "Incidunt ea ab officia a veniam.",
        "web_url": "https://gitlab.example.com/flightjs/Flight",
        "avatar_url": null,
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "namespace": "Flightjs",
        "visibility_level": 10,
        "path_with_namespace": "flightjs/Flight",
        "default_branch": "master",
        "ci_config_path": null,
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "http_url": "https://gitlab.example.com/flightjs/Flight.git"
      },
      "commits": [
        {
          "id": "f15b32277d2c55c6c595845a87109b09c913c556",
          "message": "v1.5.2\n",
          "title": "v1.5.2",
          "timestamp": "2017-06-19T14:39:53-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/f15b32277d2c55c6c595845a87109b09c913c556",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "message": "Merge pull request #378 from flightjs/alunny/publish_lib\n\npublish lib and index to npm",
          "title": "Merge pull request #378 from flightjs/alunny/publish_lib",
          "timestamp": "2017-06-16T10:26:39-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/8749d49930866a4871fa086adbd7d2057fcc3ebb",
          "author": {
            "name": "angus croll",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        },
        {
          "id": "468abc807a2b2572f43e72c743b76cee6db24025",
          "message": "publish lib and index to npm\n",
          "title": "publish lib and index to npm",
          "timestamp": "2017-06-16T10:23:04-07:00",
          "url": "https://gitlab.example.com/flightjs/Flight/-/commit/468abc807a2b2572f43e72c743b76cee6db24025",
          "author": {
            "name": "Andrew Lunny",
            "email": "[REDACTED]"
          },
          "added": [],
          "modified": [
            "package.json"
          ],
          "removed": []
        }
      ],
      "total_commits_count": 3,
      "push_options": {},
      "repository": {
        "name": "Flight",
        "url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "description": "Incidunt ea ab officia a veniam.",
        "homepage": "https://gitlab.example.com/flightjs/Flight",
        "git_http_url": "https://gitlab.example.com/flightjs/Flight.git",
        "git_ssh_url": "ssh://git@gitlab.example.com:2222/flightjs/Flight.git",
        "visibility_level": 10
      }
    },
    "response_headers": {
      "Date": "Sun, 26 May 2024 03:03:19 GMT",
      "Content-Type": "application/json; charset=utf-8",
      "Content-Length": "16",
      "Connection": "close",
      "X-Powered-By": "Express",
      "Access-Control-Allow-Origin": "*",
      "X-Pd-Status": "sent to primary"
    },
    "response_body": "{\"success\":true}",
    "execution_duration": 1.0716120000000728,
    "response_status": "200"
  }
]

プロジェクトのWebhookイベントを再送信する

特定のプロジェクトのWebhookイベントを再送信します。

このエンドポイントには、プロジェクトのWebhookおよび認証済みユーザーごとに、1分あたり5つのリクエストのレート制限があります。GitLab Self-ManagedおよびGitLab Dedicatedでこの制限を無効にするには、管理者が機能フラグを無効にすることができます。web_hook_event_resend_api_endpoint_rate_limitという名前です。

POST /projects/:id/hooks/:hook_id/events/:hook_event_id/resend

サポートされている属性は以下のとおりです:

属性型必須説明
hook_event_id整数はいプロジェクトのWebhookイベントのID。
hook_id整数はいプロジェクトのWebhookのID。

レスポンス例:

{
  "response_status": 200
}

プロジェクトにWebhookを追加する

指定されたプロジェクトにWebhookを追加します。

POST /projects/:id/hooks

サポートされている属性は以下のとおりです:

属性型必須説明
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
url文字列はいプロジェクトのWebhook URL。
branch_filter_strategy文字列いいえブランチでプッシュイベントをフィルタリングします。使用可能な値は、wildcard（デフォルト）、regex、およびall_branchesです。
confidential_issues_eventsブール値いいえ機密のイシューイベントでプロジェクトのWebhookをトリガーします。
confidential_note_eventsブール値いいえ機密のメモイベントでプロジェクトのWebhookをトリガーします。
custom_headers配列いいえプロジェクトのWebhookのカスタムヘッダー。
custom_webhook_template文字列いいえプロジェクトのWebhookのカスタムWebhookテンプレート。
deployment_eventsブール値いいえデプロイイベントでプロジェクトのWebhookをトリガーします。
description文字列いいえWebhookの説明。
enable_ssl_verificationブール値いいえWebhookをトリガーするときに、SSL検証を実行します。
feature_flag_eventsブール値いいえ機能フラグイベントでプロジェクトのWebhookをトリガーします。
issues_eventsブール値いいえイシューイベントでプロジェクトのWebhookをトリガーします。
job_eventsブール値いいえジョブイベントでプロジェクトのWebhookをトリガーします。
merge_requests_eventsブール値いいえマージリクエストイベントでプロジェクトのWebhookをトリガーします。
milestone_eventsブール値いいえマイルストーンイベントでプロジェクトのWebhookをトリガーします。
name文字列いいえプロジェクトのWebhookの名前。
note_eventsブール値いいえメモイベントでプロジェクトのWebhookをトリガーします。
pipeline_eventsブール値いいえパイプラインイベントでプロジェクトのWebhookをトリガーします。
push_eventsブール値いいえプッシュイベントでプロジェクトのWebhookをトリガーします。
push_events_branch_filter文字列いいえ一致するブランチのみのプッシュイベントでプロジェクトのWebhookをトリガーします。
releases_eventsブール値いいえリリースイベントでプロジェクトのWebhookをトリガーします。
resource_access_token_eventsブール値いいえプロジェクトアクセストークンの有効期限イベントでプロジェクトのWebhookをトリガーします。
tag_push_eventsブール値いいえタグ付けイベントでプロジェクトのWebhookをトリガーします。
token文字列いいえ受信したペイロードを検証するためのシークレットトークン。トークンはレスポンスで返されません。
wiki_page_eventsブール値いいえWikiイベントでプロジェクトのWebhookをトリガーします。

プロジェクトのWebhookを編集する

指定されたプロジェクトのプロジェクトWebhookを編集します。

PUT /projects/:id/hooks/:hook_id

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
url文字列はいプロジェクトのWebhook URL。
branch_filter_strategy文字列いいえブランチでプッシュイベントをフィルタリングします。使用可能な値は、wildcard（デフォルト）、regex、およびall_branchesです。
custom_headers配列いいえプロジェクトのWebhookのカスタムヘッダー。
custom_webhook_template文字列いいえプロジェクトのWebhookのカスタムWebhookテンプレート。
description文字列いいえプロジェクトWebhookの説明。
confidential_issues_eventsブール値いいえ機密のイシューイベントでプロジェクトのWebhookをトリガーします。
confidential_note_eventsブール値いいえ機密のメモイベントでプロジェクトのWebhookをトリガーします。
deployment_eventsブール値いいえデプロイイベントでプロジェクトのWebhookをトリガーします。
enable_ssl_verificationブール値いいえフックをトリガーするときに、SSL検証を実行します。
feature_flag_eventsブール値いいえ機能フラグイベントでプロジェクトのWebhookをトリガーします。
issues_eventsブール値いいえイシューイベントでプロジェクトのWebhookをトリガーします。
job_eventsブール値いいえジョブイベントでプロジェクトのWebhookをトリガーします。
merge_requests_eventsブール値いいえマージリクエストイベントでプロジェクトのWebhookをトリガーします。
milestone_eventsブール値いいえマイルストーンイベントでプロジェクトのWebhookをトリガーします。
name文字列いいえプロジェクトのWebhookの名前。
note_eventsブール値いいえメモイベントでプロジェクトのWebhookをトリガーします。
pipeline_eventsブール値いいえパイプラインイベントでプロジェクトのWebhookをトリガーします。
push_eventsブール値いいえプッシュイベントでプロジェクトのWebhookをトリガーします。
push_events_branch_filter文字列いいえ一致するブランチのみのプッシュイベントでプロジェクトのWebhookをトリガーします。
releases_eventsブール値いいえリリースイベントでプロジェクトのWebhookをトリガーします。
resource_access_token_eventsブール値いいえプロジェクトアクセストークンの有効期限イベントでプロジェクトのWebhookをトリガーします。
tag_push_eventsブール値いいえタグ付けイベントでプロジェクトのWebhookをトリガーします。
token文字列いいえ受信したペイロードを検証するためのシークレットトークン。レスポンスで返されません。Webhook URLを変更すると、シークレットトークンはリセットされ、保持されません。
wiki_page_eventsブール値いいえWikiページイベントでプロジェクトのWebhookをトリガーします。

プロジェクトのWebhookを削除する

プロジェクトからWebhookを削除します。このメソッドは冪等であり、複数回呼び出すことができます。プロジェクトのWebhookは利用可能であるか、そうでないかのどちらかです。

DELETE /projects/:id/hooks/:hook_id

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。

プロジェクトのWebhookが利用可能かどうかで、JSONレスポンスが異なることに注意してください。プロジェクトのフックがJSONレスポンスで返される前に利用可能な場合、または空のレスポンスが返される場合。

テストプロジェクトのWebhookをトリガーする

指定されたプロジェクトのテストプロジェクトWebhookをトリガーします。

GitLab 17.0以降、このエンドポイントには特別なレート制限があります:

  • GitLab 17.0では、レートはプロジェクトのWebhookごとに1分あたり3つのリクエストでした。
  • GitLab 17.1では、これはプロジェクトおよび認証済みユーザーごとに1分あたり5つのリクエストに変更されました。

GitLab Self-ManagedおよびGitLab Dedicatedでこの制限を無効にするには、管理者が機能フラグを無効にすることができます。web_hook_test_api_endpoint_rate_limitという名前です。

POST /projects/:id/hooks/:hook_id/test/:trigger

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
trigger文字列はいpush_events、tag_push_events、issues_events、confidential_issues_events、note_events、merge_requests_events、job_events、pipeline_events、wiki_page_events、releases_events、milestone_events、emoji_events、またはresource_access_token_eventsのいずれか。

レスポンス例:

{"message":"201 Created"}

カスタムヘッダーを設定する

PUT /projects/:id/hooks/:hook_id/custom_headers/:key

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はいカスタムヘッダーのキー。
value文字列はいカスタムヘッダーの値。

成功すると、このエンドポイントはレスポンスコード204 No Contentを返します。

カスタムヘッダーを削除する

DELETE /projects/:id/hooks/:hook_id/custom_headers/:key

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はいカスタムヘッダーのキー。

成功すると、このエンドポイントはレスポンスコード204 No Contentを返します。

URL変数を設定する

PUT /projects/:id/hooks/:hook_id/url_variables/:key

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はいURL変数のキー。
value文字列はいURL変数の値。

成功すると、このエンドポイントはレスポンスコード204 No Contentを返します。

URL変数を削除する

DELETE /projects/:id/hooks/:hook_id/url_variables/:key

サポートされている属性は以下のとおりです:

属性型必須説明
hook_id整数はいプロジェクトのWebhookのID。
id整数または文字列はいプロジェクトのIDまたはURLエンコードされたパス。
key文字列はいURL変数のキー。

成功すると、このエンドポイントはレスポンスコード204 No Contentを返します。