System hooks API

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

Use this API to manage system hooks. System hooks are different from group webhooks that impact all projects and subgroups in a group and project webhooks that are limited to a single project.

Each system hook belongs to one organization, and the organization_id attribute shows which one. All endpoints work only with the hooks of the current organization:

Lists return only hooks in the current organization.
New hooks are created in the current organization.
Requests for a hook in another organization return 404 Not Found. These requests include retrieving, updating, deleting, and testing the hook and managing its URL variables and custom headers.

Prerequisites:

Administrator access.

Organization administrators who are not instance administrators cannot use this API. They can manage system hooks in the Organization Admin area. For more information, see manage system hooks as an organization administrator.

List all system hooks

Lists all system hooks in the current organization.

GET /hooks

Example request:

shell
curl --request GET \
  --header "PRIVATE-TOKEN: <your_access_token>" \
  --url "https://gitlab.example.com/api/v4/hooks"

Example response:

json
[
  {
    "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,
    "organization_id": 1,
    "alert_status": "executable",
    "disabled_until": null,
    "url_variables": [],
    "push_events_branch_filter": "",
    "branch_filter_strategy": "wildcard",
    "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
    "custom_headers": [
      {
        "key": "X-Custom-Header"
      }
    ],
    "token_present": false,
    "signing_token_present": false
  }
]

Retrieve system hook

Retrieves a system hook by its ID.

GET /hooks/:id

Attribute	Type	Required	Description
`id`	integer	Yes	The ID of the hook.

Example request:

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

Example response:

json
{
  "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,
  "organization_id": 1,
  "alert_status": "executable",
  "disabled_until": null,
  "url_variables": [],
  "push_events_branch_filter": "",
  "branch_filter_strategy": "wildcard",
  "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
  "custom_headers": [
    {
      "key": "X-Custom-Header"
    }
  ],
  "token_present": false,
  "signing_token_present": false
}

Add new system hook

Adds a new system hook.

This endpoint has a rate limit of five requests per minute for each authenticated user. Administrators can change this limit.

POST /hooks

Attribute	Type	Required	Description
`url`	string	Yes	The hook URL.
`branch_filter_strategy`	string	No	Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches`.
`custom_webhook_template`	string	No	Custom template for the request payload.
`description`	string	No	Description of the hook.
`enable_ssl_verification`	boolean	No	Do SSL verification when triggering the hook.
`merge_requests_events`	boolean	No	Trigger hook on merge request events.
`name`	string	No	Name of the hook.
`push_events`	boolean	No	When true, the hook fires on push events.
`push_events_branch_filter`	string	No	Trigger hook on push events for matching branches only.
`repository_update_events`	boolean	No	Trigger hook on repository update events.
`signing_token`	string	No	HMAC signing token used to compute the `webhook-signature` header. Must be in `whsec_<base64>` format encoding a 32-byte key. Not returned in the response.
`tag_push_events`	boolean	No	When true, the hook fires on new tags being pushed.
`token`	string	No	Secret token to validate received payloads. Not returned in the response.

Example request:

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

Example response:

json
[
  {
    "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,
    "organization_id": 1,
    "alert_status": "executable",
    "disabled_until": null,
    "url_variables": [],
    "push_events_branch_filter": "",
    "branch_filter_strategy": "wildcard",
    "custom_webhook_template": "{\"event\":\"{{object_kind}}\"}",
    "custom_headers": [
      {
        "key": "X-Custom-Header"
      }
    ],
    "token_present": false,
    "signing_token_present": false
  }
]

Update system hook

Updates an existing system hook.

PUT /hooks/:hook_id

Attribute	Type	Required	Description
`hook_id`	integer	Yes	The ID of the system hook.
`branch_filter_strategy`	string	No	Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches`.
`custom_webhook_template`	string	No	Custom template for the request payload.
`description`	string	No	Description of the hook.
`enable_ssl_verification`	boolean	No	Do SSL verification when triggering the hook.
`merge_requests_events`	boolean	No	Trigger hook on merge request events.
`name`	string	No	Name of the hook.
`push_events`	boolean	No	When true, the hook fires on push events.
`push_events_branch_filter`	string	No	Trigger hook on push events for matching branches only.
`repository_update_events`	boolean	No	Trigger hook on repository update events.
`signing_token`	string	No	HMAC signing token used to compute the `webhook-signature` header. Must be in `whsec_<base64>` format encoding a 32-byte key. Not returned in the response.
`tag_push_events`	boolean	No	When true, the hook fires on new tags being pushed.
`token`	string	No	Secret token to validate received payloads. Not returned in the response.
`url`	string	No	The hook URL.

Test system hook

Executes the system hook with mock data.

POST /hooks/:id

Attribute	Type	Required	Description
`id`	integer	Yes	The ID of the hook.

Example request:

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

The response is always the mock data:

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

Attribute	Type	Required	Description
`id`	integer	Yes	The ID of the hook.

Example request:

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

Set a URL variable

PUT /hooks/:hook_id/url_variables/:key

Supported attributes:

Attribute	Type	Required	Description
`hook_id`	integer	Yes	ID of the system hook.
`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

DELETE /hooks/:hook_id/url_variables/:key

Supported attributes:

Attribute	Type	Required	Description
`hook_id`	integer	Yes	ID of the system hook.
`key`	string	Yes	Key of the URL variable.

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

Was this page helpful?