Project webhooks

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab 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,
  "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"
    }
  ]
}

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 GitLab Self-Managed 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

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 issue 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.
`feature_flag_events`	boolean	No	Trigger project webhook on feature flag events.
`issues_events`	boolean	No	Trigger project webhook on issue events.
`job_events`	boolean	No	Trigger project webhook on job events.
`merge_requests_events`	boolean	No	Trigger project webhook on merge request 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

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 issue 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.
`feature_flag_events`	boolean	No	Trigger project webhook on feature flag events.
`issues_events`	boolean	No	Trigger project webhook on issue events.
`job_events`	boolean	No	Trigger project webhook on job events.
`merge_requests_events`	boolean	No	Trigger project webhook on merge request 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 GitLab Self-Managed 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.

Set a URL variable

History

PUT /projects/:id/hooks/:hook_id/url_variables/: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 URL variable.
`value`	string	Yes	Value of the URL variable.

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

Delete a URL variable

History

DELETE /projects/:id/hooks/:hook_id/url_variables/: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 URL variable.

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

Docs

Edit this page to fix an error or add an improvement in a merge request.

Create an issue to suggest an improvement to this page.

Product

Create an issue if there's something you don't like about this feature.

Propose functionality by submitting a feature request.

Feature availability and product trials

View pricing to see all GitLab tiers and features, or to upgrade.

Try GitLab for free with access to all features for 30 days.

Get help

If you didn't find what you were looking for, search the docs.

If you want help with something specific and could use community support, post on the GitLab forum.

For problems setting up or using this feature (depending on your GitLab subscription).

Request support

Project webhooks

List webhooks for a project

Get a project webhook

Get a list of project webhook events

Resend a project webhook event

Add a webhook to a project

Edit a project webhook

Delete project webhook

Trigger a test project webhook

Set a custom header

Delete a custom header

Set a URL variable

Delete a URL variable

Help & feedback

Docs

Product

Feature availability and product trials

Get help