Group webhooks API

  • Tier: Premium, Ultimate
  • Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

Interact with group webhooks by using the REST API. Also called group hooks. These are different from system hooks that are system wide and project webhooks that are limited to one project.

Prerequisites:

  • You must be an Administrator or have the Owner role for the group.

List group hooks

Get a list of group hooks

GET /groups/:id/hooks

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks"

Example response:

[
  {
    "id": 1,
    "url": "http://example.com/hook",
    "name": "Test group hook",
    "description": "This is a test group hook.",
    "created_at": "2024-09-01T09:10:54.854Z",
    "push_events": true,
    "tag_push_events": false,
    "merge_requests_events": false,
    "repository_update_events": false,
    "enable_ssl_verification": true,
    "alert_status": "executable",
    "disabled_until": null,
    "url_variables": [],
    "push_events_branch_filter": null,
    "branch_filter_strategy": "all_branches",
    "group_id": 99,
    "issues_events": false,
    "confidential_issues_events": false,
    "note_events": false,
    "confidential_note_events": false,
    "pipeline_events": false,
    "wiki_page_events": false,
    "job_events": false,
    "deployment_events": false,
    "feature_flag_events": false,
    "releases_events": false,
    "subgroup_events": false,
    "emoji_events": false,
    "resource_access_token_events": false,
    "member_events": false,
    "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
    "custom_headers": [
      {
        "key": "Authorization"
      }
    ]
  }
]

Get a group hook

Get a specific hook for a group.

GET /groups/:id/hooks/:hook_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group.
hook_idintegeryesThe ID of a group hook.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1"

Example response:

{
  "id": 1,
  "url": "http://example.com/hook",
  "name": "Hook name",
  "description": "Hook description",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "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,
  "feature_flag_events": false,
  "releases_events": true,
  "subgroup_events": true,
  "member_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"
    }
  ]
}

Get group hook events

History

Get a list of events for a specific group hook in the past seven days from start date.

GET /groups/:id/hooks/:hook_id/events

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group.
hook_idintegerYesThe ID of a project hook.
statusinteger or stringNoThe response status code of the events, for example: 200 or 500. You can search by status category: successful (200-299), client_failure (400-499), and server_failure (500-599).
pageintegerNoPage to retrieve. Defaults to 1.
per_pageintegerNoNumber of records to return per page. Defaults to 20.

Example request:

curl --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/events"

Example response:

[
  {
    "id": 1,
    "url": "https://example.net/",
    "trigger": "push_hooks",
    "request_headers": {
      "Content-Type": "application/json",
      "User-Agent": "GitLab/17.1.0-pre",
      "Idempotency-Key": "a5461c4d-9c7f-4af9-add6-cddebe3c426f",
      "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",
      "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": "1f0a54f0-0529-408d-a5b8-a2a98ff5f94a",
      "X-Gitlab-Event": "Push Hook",
      "X-Gitlab-Webhook-UUID": "a753eedb-1d72-4549-9ca7-eac8ea8e50dd",
      "X-Gitlab-Instance": "https://gitlab.example.com:3000",
      "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"
  }
]

Resend group hook event

History

Resends a specific hook event.

This endpoint has a rate limit of five requests per minute for each hook and authenticated user. To disable this limit on GitLab Self-Managed and GitLab Dedicated, an administrator can disable the feature flag named web_hook_event_resend_api_endpoint_rate_limit.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group.
hook_idintegerYesThe ID of a group hook.
hook_event_idintegerYesThe ID of a hook event.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/events/1/resend"

Example response:

{
  "response_status": 200
}

Add a group hook

Adds a hook to a specified group.

POST /groups/:id/hooks

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group.
urlstringyesThe hook URL.
namestringnoName of the hook (introduced in GitLab 17.1).
descriptionstringnoDescription of the hook (introduced in GitLab 17.1).
push_eventsbooleannoTrigger hook on push events.
push_events_branch_filterstringnoTrigger hook on push events for matching branches only.
branch_filter_strategystringnoFilter push events by branch. Possible values are wildcard (default), regex, and all_branches.
issues_eventsbooleannoTrigger hook on issue events.
confidential_issues_eventsbooleannoTrigger hook on confidential issue events.
merge_requests_eventsbooleannoTrigger hook on merge request events.
tag_push_eventsbooleannoTrigger hook on tag push events.
note_eventsbooleannoTrigger hook on note events.
confidential_note_eventsbooleannoTrigger hook on confidential note events.
job_eventsbooleannoTrigger hook on job events.
pipeline_eventsbooleannoTrigger hook on pipeline events.
wiki_page_eventsbooleannoTrigger hook on wiki page events.
deployment_eventsbooleannoTrigger hook on deployment events.
feature_flag_eventsbooleannoTrigger hook on feature flag events.
releases_eventsbooleannoTrigger hook on release events.
subgroup_eventsbooleannoTrigger hook on subgroup events.
member_eventsbooleannoTrigger hook on member events.
enable_ssl_verificationbooleannoDo SSL verification when triggering the hook.
tokenstringnoSecret token to validate received payloads; not returned in the response.
resource_access_token_eventsbooleannoTrigger hook on project access token expiry events.
custom_webhook_templatestringnoCustom webhook template for the hook.
custom_headersarrayNoCustom headers for the hook.

Example request:

curl --request POST \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/hooks" \
  --data '{"url": "https://example.com/hook", "name": "My Hook", "description": "Hook description"}'

Example response:

{
  "id": 42,
  "url": "https://example.com/hook",
  "name": "My Hook",
  "description": "Hook description",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "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,
  "feature_flag_events": true,
  "releases_events": true,
  "subgroup_events": true,
  "member_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}}\"}",
}

Edit group hook

Edits a hook for a specified group.

PUT /groups/:id/hooks/:hook_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringyesThe ID or URL-encoded path of the group.
hook_idintegeryesThe ID of the group hook.
urlstringyesThe hook URL.
namestringnoName of the hook (introduced in GitLab 17.1).
descriptionstringnoDescription of the hook (introduced in GitLab 17.1).
push_eventsbooleannoTrigger hook on push events.
push_events_branch_filterstringnoTrigger hook on push events for matching branches only.
branch_filter_strategystringnoFilter push events by branch. Possible values are wildcard (default), regex, and all_branches.
issues_eventsbooleannoTrigger hook on issue events.
confidential_issues_eventsbooleannoTrigger hook on confidential issue events.
merge_requests_eventsbooleannoTrigger hook on merge request events.
tag_push_eventsbooleannoTrigger hook on tag push events.
note_eventsbooleannoTrigger hook on note events.
confidential_note_eventsbooleannoTrigger hook on confidential note events.
job_eventsbooleannoTrigger hook on job events.
pipeline_eventsbooleannoTrigger hook on pipeline events.
wiki_page_eventsbooleannoTrigger hook on wiki page events.
deployment_eventsbooleannoTrigger hook on deployment events.
feature_flag_eventsbooleannoTrigger hook on feature flag events.
releases_eventsbooleannoTrigger hook on release events.
subgroup_eventsbooleannoTrigger hook on subgroup events.
member_eventsbooleannoTrigger hook on member events.
enable_ssl_verificationbooleannoDo SSL verification when triggering the hook.
service_access_tokens_expiration_enforcedbooleannoRequire service account access tokens to have an expiration date.
tokenstringnoSecret token to validate received payloads. Not returned in the response. When you change the webhook URL, the secret token is reset and not retained.
resource_access_token_eventsbooleannoTrigger hook on project access token expiry events.
custom_webhook_templatestringnoCustom webhook template for the hook.
custom_headersarraynoCustom headers for the hook.

Example request:

curl --request POST \
  --header "content-type: application/json" \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/groups/3/hooks/1" \
  --data '{"url": "https://example.com/hook", "name": "New hook name", "description": "Changed hook description"}'

Example response:

{
  "id": 1,
  "url": "https://example.com/hook",
  "name": "New hook name",
  "description": "Changed hook description",
  "group_id": 3,
  "push_events": true,
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "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,
  "feature_flag_events": true,
  "releases_events": true,
  "subgroup_events": true,
  "member_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"
    }
  ]
}

Delete a group hook

Deletes a hook from a group. This is an idempotent method and can be called multiple times. Either the hook is available or not.

DELETE /groups/:id/hooks/:hook_id

Supported attributes:

AttributeTypeRequiredDescription
idinteger/stringyesThe ID or URL-encoded path of the group.
hook_idintegeryesThe ID of the group hook.

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1"

On success, no message is returned.

Trigger a test group hook

History

Trigger a test hook for a specified group.

This endpoint has a rate limit of five requests per minute for each group and authenticated user. To disable this limit on GitLab Self-Managed and GitLab Dedicated, an administrator can disable the feature flag named web_hook_test_api_endpoint_rate_limit.

POST /groups/:id/hooks/:hook_id/test/:trigger
AttributeTypeRequiredDescription
hook_idintegerYesThe ID of the group hook.
idinteger or stringYesThe ID or URL-encoded path of the group.
triggerstringYesOne of push_events, tag_push_events, issues_events, confidential_issues_events, note_events, merge_requests_events, job_events, pipeline_events, wiki_page_events, releases_events, emoji_events, or resource_access_token_events.

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/test/push_events"

Example response:

{"message":"201 Created"}

Set a custom header

History

Sets a custom header.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
hook_idintegerYesThe ID of the group hook.
keystringYesThe key of the custom header.
valuestringYesThe value of the custom header.

Example request:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/custom_headers/header_key?value='header_value'"

On success, no message is returned.

Delete a custom header

History

Deletes a custom header.

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

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
hook_idintegerYesThe ID of the group hook.
keystringYesThe key of the custom header.

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/custom_headers/header_key"

On success, no message is returned.

Set a URL variable

History
PUT /groups/:id/hooks/:hook_id/url_variables/:key

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
hook_idintegerYesThe ID of the group hook.
keystringYesThe key of the URL variable.
valuestringYesThe value of the URL variable.

Example request:

curl --request PUT --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/url_variables/my_key?value='my_key_value'"

On success, no message is returned.

Delete a URL variable

History
DELETE /groups/:id/hooks/:hook_id/url_variables/:key

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesThe ID or URL-encoded path of the group.
hook_idintegerYesThe ID of the group hook.
keystringYesThe key of the URL variable.

Example request:

curl --request DELETE --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/groups/3/hooks/1/url_variables/my_key"

On success, no message is returned.