ContextQMD
Back to Gitlabhq

Project webhooks API

doc/api/project_webhooks.md

18.11.225.6 KB
Original Source

{{< details >}}

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

{{< /details >}}

Use this API to manage project webhooks. Project webhooks are different from system hooks that impact the entire instance, and group webhooks that impact all projects and subgroups in a group.

Prerequisites:

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

List webhooks for a project

Get a list of project webhooks.

plaintext
GET /projects/:id/hooks

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.

Retrieve a project webhook

Retrieves a specified webhook for a project.

plaintext
GET /projects/:id/hooks/:hook_id

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of a project webhook.
idinteger or stringYesID or URL-encoded path of the project.

Example response:

json
{
  "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"
    }
  ]
}

List project webhook events

{{< history >}}

{{< /history >}}

Lists all events for a specified project webhook in the past 7 days from start date.

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of a project webhook.
idinteger or stringYesID or URL-encoded path of the project.
statusinteger or stringNoResponse 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 response:

json
[
  {
    "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://[email protected]: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://[email protected]:2222/flightjs/Flight.git",
        "ssh_url": "ssh://[email protected]: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://[email protected]: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://[email protected]: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://[email protected]: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://[email protected]:2222/flightjs/Flight.git",
        "ssh_url": "ssh://[email protected]: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://[email protected]: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://[email protected]: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 >}}

{{< /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.

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

Supported attributes:

AttributeTypeRequiredDescription
hook_event_idintegerYesID of a project webhook event.
hook_idintegerYesID of a project webhook.

Example response:

json
{
  "response_status": 200
}

Add a webhook to a project

{{< history >}}

  • name and description attributes introduced in GitLab 17.1.

{{< /history >}}

Add a webhook to a specified project.

plaintext
POST /projects/:id/hooks

Supported attributes:

AttributeTypeRequiredDescription
idinteger or stringYesID or URL-encoded path of the project.
urlstringYesProject webhook URL.
branch_filter_strategystringNoFilter push events by branch. Possible values are wildcard (default), regex, and all_branches.
confidential_issues_eventsbooleanNoTrigger project webhook on confidential issue events.
confidential_note_eventsbooleanNoTrigger project webhook on confidential note events.
custom_headersarrayNoCustom headers for the project webhook.
custom_webhook_templatestringNoCustom webhook template for the project webhook.
deployment_eventsbooleanNoTrigger project webhook on deployment events.
descriptionstringNoDescription of the webhook.
enable_ssl_verificationbooleanNoDo SSL verification when triggering the webhook.
feature_flag_eventsbooleanNoTrigger project webhook on feature flag events.
issues_eventsbooleanNoTrigger project webhook on issue events.
job_eventsbooleanNoTrigger project webhook on job events.
merge_requests_eventsbooleanNoTrigger project webhook on merge request events.
milestone_eventsbooleanNoTrigger project webhook on milestone events.
namestringNoName of the project webhook.
note_eventsbooleanNoTrigger project webhook on note events.
pipeline_eventsbooleanNoTrigger project webhook on pipeline events.
push_eventsbooleanNoTrigger project webhook on push events.
push_events_branch_filterstringNoTrigger project webhook on push events for matching branches only.
releases_eventsbooleanNoTrigger project webhook on release events.
resource_access_token_eventsbooleanNoTrigger project webhook on project access token expiry events.
tag_push_eventsbooleanNoTrigger project webhook on tag push events.
tokenstringNoSecret token to validate received payloads; the token isn't returned in the response.
wiki_page_eventsbooleanNoTrigger project webhook on wiki events.
resource_deploy_token_eventsbooleanNoTrigger project webhook on project deploy token expiry events.

Update a project webhook

{{< history >}}

  • name and description attributes introduced in GitLab 17.1.

{{< /history >}}

Updates a project webhook for a specified project.

plaintext
PUT /projects/:id/hooks/:hook_id

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID or URL-encoded path of the project.
urlstringYesProject webhook URL.
branch_filter_strategystringNoFilter push events by branch. Possible values are wildcard (default), regex, and all_branches.
custom_headersarrayNoCustom headers for the project webhook.
custom_webhook_templatestringNoCustom webhook template for the project webhook.
descriptionstringNoDescription of the project webhook.
confidential_issues_eventsbooleanNoTrigger project webhook on confidential issue events.
confidential_note_eventsbooleanNoTrigger project webhook on confidential note events.
deployment_eventsbooleanNoTrigger project webhook on deployment events.
enable_ssl_verificationbooleanNoDo SSL verification when triggering the hook.
feature_flag_eventsbooleanNoTrigger project webhook on feature flag events.
issues_eventsbooleanNoTrigger project webhook on issue events.
job_eventsbooleanNoTrigger project webhook on job events.
merge_requests_eventsbooleanNoTrigger project webhook on merge request events.
milestone_eventsbooleanNoTrigger project webhook on milestone events.
namestringNoName of the project webhook.
note_eventsbooleanNoTrigger project webhook on note events.
pipeline_eventsbooleanNoTrigger project webhook on pipeline events.
push_eventsbooleanNoTrigger project webhook on push events.
push_events_branch_filterstringNoTrigger project webhook on push events for matching branches only.
releases_eventsbooleanNoTrigger project webhook on release events.
resource_access_token_eventsbooleanNoTrigger project webhook on project access token expiry events.
tag_push_eventsbooleanNoTrigger project webhook on tag push events.
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.
wiki_page_eventsbooleanNoTrigger project webhook on wiki page events.
resource_deploy_token_eventsbooleanNoTrigger project webhook on project deploy token expiry events.

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.

plaintext
DELETE /projects/:id/hooks/:hook_id

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID 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 >}}

{{< /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.

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID or URL-encoded path of the project.
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, milestone_events, emoji_events,resource_access_token_events or resource_deploy_token_events.

Example response:

json
{"message":"201 Created"}

Set a custom header

{{< history >}}

{{< /history >}}

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID or URL-encoded path of the project.
keystringYesKey of the custom header.
valuestringYesValue of the custom header.

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

Delete a custom header

{{< history >}}

{{< /history >}}

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID or URL-encoded path of the project.
keystringYesKey of the custom header.

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

Set a URL variable

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID or URL-encoded path of the project.
keystringYesKey of the URL variable.
valuestringYesValue of the URL variable.

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

Delete a URL variable

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the project webhook.
idinteger or stringYesID or URL-encoded path of the project.
keystringYesKey of the URL variable.

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