Project webhooks

Tier: Free, Premium, Ultimate Offering: GitLab.com, Self-managed, GitLab Dedicated

Manage project webhooks by using the REST API. Project webhooks are different to system hooks, which are system-wide, and group webhooks.

Prerequisites:

  • You must be an administrator or have at least the Maintainer role for the project.

List webhooks for a project

Get a list of project webhooks. 

GET /projects/:id/hooks

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.

Get a project webhook

Get a specific webhook for a project. 

GET /projects/:id/hooks/:hook_id

Supported attributes:

Attribute Type Required Description
hook_id integer Yes ID of a project webhook.
id integer or string Yes ID or URL-encoded path of the project.

Example response: 

{
  "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,
  "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 a list of project webhook events

History

Get a list of events for a specific project webhook in the past 7 days from start date. 

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

Supported attributes:

Attribute Type Required Description
hook_id integer Yes ID of a project webhook.
id integer or string Yes ID or URL-encoded path of the project.
status integer or string No 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).
page integer No Page to retrieve. Defaults to 1.
per_page integer No Number of records to return per page. Defaults to 20.

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": "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"
  }
]

Resend a project webhook event

History

Resend a specific project webhook event.

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

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

Supported attributes:

Attribute Type Required Description
hook_id integer Yes ID of a project webhook.
hook_event_id integer Yes ID of a project webhook event.

Example response: 

{
  "response_status": 200
}

Add a webhook to a project

History
  • name and description attributes introduced in GitLab 17.1.

Add a webhook to a specified project. 

POST /projects/:id/hooks

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
url string Yes Project webhook URL.
name string No Name of the project webhook.
description string No Description of the webhook.
confidential_issues_events boolean No Trigger project webhook on confidential issues events.
confidential_note_events boolean No Trigger project webhook on confidential note events.
deployment_events boolean No Trigger project webhook on deployment events.
enable_ssl_verification boolean No Do SSL verification when triggering the webhook.
issues_events boolean No Trigger project webhook on issues events.
job_events boolean No Trigger project webhook on job events.
merge_requests_events boolean No Trigger project webhook on merge requests events.
note_events boolean No Trigger project webhook on note events.
pipeline_events boolean No Trigger project webhook on pipeline events.
push_events_branch_filter string No Trigger project webhook on push events for matching branches only.
branch_filter_strategy string No Filter push events by branch. Possible values are wildcard (default), regex, and all_branches.
push_events boolean No Trigger project webhook on push events.
releases_events boolean No Trigger project webhook on release events.
tag_push_events boolean No Trigger project webhook on tag push events.
token string No Secret token to validate received payloads; the token isn’t returned in the response.
wiki_page_events boolean No Trigger project webhook on wiki events.
resource_access_token_events boolean No Trigger project webhook on project access token expiry events.
custom_webhook_template string No Custom webhook template for the project webhook.
custom_headers array No Custom headers for the project webhook.

Edit a project webhook

History
  • name and description attributes introduced in GitLab 17.1.

Edit a project webhook for a specified project. 

PUT /projects/:id/hooks/:hook_id

Supported attributes:

Attribute Type Required Description
hook_id integer Yes ID of the project webhook.
id integer or string Yes ID or URL-encoded path of the project.
url string Yes Project webhook URL.
name string No Name of the project webhook.
description string No Description of the project webhook.
confidential_issues_events boolean No Trigger project webhook on confidential issues events.
confidential_note_events boolean No Trigger project webhook on confidential note events.
deployment_events boolean No Trigger project webhook on deployment events.
enable_ssl_verification boolean No Do SSL verification when triggering the hook.
issues_events boolean No Trigger project webhook on issues events.
job_events boolean No Trigger project webhook on job events.
merge_requests_events boolean No Trigger project webhook on merge requests events.
note_events boolean No Trigger project webhook on note events.
pipeline_events boolean No Trigger project webhook on pipeline events.
push_events_branch_filter string No Trigger project webhook on push events for matching branches only.
branch_filter_strategy string No Filter push events by branch. Possible values are wildcard (default), regex, and all_branches.
push_events boolean No Trigger project webhook on push events.
releases_events boolean No Trigger project webhook on release events.
tag_push_events boolean No Trigger project webhook on tag push events.
token string No Secret token to validate received payloads. Not returned in the response. When you change the webhook URL, the secret token is reset and not retained.
wiki_page_events boolean No Trigger project webhook on wiki page events.
resource_access_token_events boolean No Trigger project webhook on project access token expiry events.
custom_webhook_template string No Custom webhook template for the project webhook.
custom_headers array No Custom headers for the project webhook.

Delete project webhook

Remove a webhook from a project. This method is idempotent and can be called multiple times. The project webhook is either available or not. 

DELETE /projects/:id/hooks/:hook_id

Supported attributes:

Attribute Type Required Description
hook_id integer Yes ID of the project webhook.
id integer or string Yes ID or URL-encoded path of the project.

Note the JSON response differs if the project webhook is available or not. If the project hook is available before it’s returned in the JSON response or an empty response is returned.

Trigger a test project webhook

History

Trigger a test project webhook for a specified project.

In GitLab 17.0 and later, this endpoint has a special rate limit:

  • In GitLab 17.0, the rate was three requests per minute for each project webhook.
  • In GitLab 17.1, this was changed to five requests per minute for each project and authenticated user.

To disable this limit on self-managed GitLab and GitLab Dedicated, an administrator can disable the feature flag named web_hook_test_api_endpoint_rate_limit. 

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

Supported attributes:

Attribute Type Required Description
hook_id integer Yes ID of the project webhook.
id integer or string Yes ID or URL-encoded path of the project.
trigger string Yes One 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 response: 

{"message":"201 Created"}

Set a custom header

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

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
hook_id integer Yes ID of the project webhook.
key string Yes Key of the custom header.
value string Yes Value of the custom header.

On success, this endpoint returns the response code 204 No Content.

Delete a custom header

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

Supported attributes:

Attribute Type Required Description
id integer or string Yes ID or URL-encoded path of the project.
hook_id integer Yes ID of the project webhook.
key string Yes Key of the custom header.

On success, this endpoint returns the response code 204 No Content.