System hooks API

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

All methods require administrator authorization.

You can configure the URL endpoint of the system hooks from the GitLab user interface:

  1. On the left sidebar, at the bottom, select Admin.
  2. Select System hooks (/admin/hooks).

Read more about system hooks.

List system hooks

Get a list of all system hooks.

GET /hooks

Example request:

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

Example response:

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": []
  }
]

Get system hook

Get a system hook by its ID.

GET /hooks/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of the hook

Example request:

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

Example response:

[
  {
    "id": 1,
    "url": "https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at": "2016-10-31T12:32:15.192Z",
    "push_events": true,
    "tag_push_events": false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification": true,
    "url_variables": []
  }
]

Add new system hook

Add a new system hook.

POST /hooks
AttributeTypeRequiredDescription
urlstringyesThe hook URL
namestringnoName of the hook (introduced in GitLab 17.1)
descriptionstringnoDescription of the hook (introduced in GitLab 17.1)
tokenstringnoSecret token to validate received payloads; this isn’t returned in the response
push_eventsbooleannoWhen true, the hook fires on push events
tag_push_eventsbooleannoWhen true, the hook fires on new tags being pushed
merge_requests_eventsbooleannoTrigger hook on merge request events
repository_update_eventsbooleannoTrigger hook on repository update events
enable_ssl_verificationbooleannoDo SSL verification when triggering the hook
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

Example request:

curl --request POST --header "PRIVATE-TOKEN: <your_access_token>" "https://gitlab.example.com/api/v4/hooks?url=https://gitlab.example.com/hook"

Example response:

[
  {
    "id":1,
    "url":"https://gitlab.example.com/hook",
    "name": "Hook name",
    "description": "Hook description",
    "created_at":"2016-10-31T12:32:15.192Z",
    "push_events":true,
    "tag_push_events":false,
    "merge_requests_events": true,
    "repository_update_events": true,
    "enable_ssl_verification":true,
    "url_variables": []
  }
]

Update system hook

Update an existing system hook.

PUT /hooks/:hook_id
AttributeTypeRequiredDescription
hook_idintegerYesThe ID of the system hook
urlstringyesThe hook URL
tokenstringnoSecret token to validate received payloads; this isn’t returned in the response
push_eventsbooleannoWhen true, the hook fires on push events
tag_push_eventsbooleannoWhen true, the hook fires on new tags being pushed
merge_requests_eventsbooleannoTrigger hook on merge request events
repository_update_eventsbooleannoTrigger hook on repository update events
enable_ssl_verificationbooleannoDo SSL verification when triggering the hook
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

Test system hook

Executes the system hook with mock data.

POST /hooks/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of the hook

Example request:

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

The response is always the mock data:

{
   "project_id" : 1,
   "owner_email" : "example@gitlabhq.com",
   "owner_name" : "Someone",
   "name" : "Ruby",
   "path" : "ruby",
   "event_name" : "project_create"
}

Delete system hook

Deletes a system hook.

DELETE /hooks/:id
AttributeTypeRequiredDescription
idintegeryesThe ID of the hook

Example request:

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

Set a URL variable

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the system hook.
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

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

Supported attributes:

AttributeTypeRequiredDescription
hook_idintegerYesID of the system hook.
keystringYesKey of the URL variable.

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