Hooks

Use this API to manage the hooks that GitLab uses to notify external services about events:

Project webhooks are limited to a single project.
Group webhooks apply to all projects and subgroups in a group.
System hooks apply to the entire instance.

You can also test a hook, inspect its event log, resend an event, and manage its custom headers and URL variables.

Managing project webhooks requires administrator access or the Maintainer or Owner role for the project. Managing group webhooks requires administrator access or the Owner role for the group. Managing system hooks requires administrator access.

List all system hooks

GET /api/v4/hooks

Lists all system hooks for the instance.

Parameters

Name	Type	Description
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesHook
`400`	Bad Request	—

Create a system hook

POST /api/v4/hooks

Creates a system hook.

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches` Allowed values: `wildcard`, `regex`, `all_branches`
`custom_headers`	Array of objects	Custom headers
`custom_headers[].key` Required	String	Name of the header Example: `X-Custom-Header`
`custom_headers[].value` Required	String	Value of the header Example: `value`
`custom_webhook_template`	String	Custom template for the request payload
`description`	String	Description of the hook
`enable_ssl_verification`	Boolean	Do SSL verification when triggering the hook
`merge_requests_events`	Boolean	Trigger hook on merge requests events
`name`	String	Name of the hook
`push_events`	Boolean	When true, the hook fires on push events
`push_events_branch_filter`	String	Trigger hook on specified branch only
`repository_update_events`	Boolean	Trigger hook on repository update events
`signing_token`	String	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	When true, the hook fires on new tags being pushed
`token`	String	Secret token to validate received payloads; this isn’t returned in the response
`url` Required	String	The URL to send the request to Example: `http://example.com/hook`
`url_variables`	Array of objects	URL variables for interpolation
`url_variables[].key` Required	String	Name of the variable Example: `token`
`url_variables[].value` Required	String	Value of the variable Example: `123`

Responses

Code	Description	Schema
`201`	Created	APIEntitiesHook
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Retrieve a system hook

GET /api/v4/hooks/{hook_id}

Retrieves a specified system hook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the system hook

Responses

Code	Description	Schema
`200`	OK	APIEntitiesHook
`400`	Bad Request	—
`404`	Not found	—

Create a test run

POST /api/v4/hooks/{hook_id}

Creates a test run for a webhook. Executes the webhook with mock data.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—
`404`	Not Found	—

Update a system hook

PUT /api/v4/hooks/{hook_id}

Updates a specified system hook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the system hook

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches` Allowed values: `wildcard`, `regex`, `all_branches`
`custom_headers`	Array of objects	Custom headers
`custom_headers[].key` Required	String	Name of the header Example: `X-Custom-Header`
`custom_headers[].value` Required	String	Value of the header Example: `value`
`custom_webhook_template`	String	Custom template for the request payload
`description`	String	Description of the hook
`enable_ssl_verification`	Boolean	Do SSL verification when triggering the hook
`merge_requests_events`	Boolean	Trigger hook on merge requests events
`name`	String	Name of the hook
`push_events`	Boolean	When true, the hook fires on push events
`push_events_branch_filter`	String	Trigger hook on specified branch only
`repository_update_events`	Boolean	Trigger hook on repository update events
`signing_token`	String	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	When true, the hook fires on new tags being pushed
`token`	String	Secret token to validate received payloads; this isn’t returned in the response
`url`	String	The URL to send the request to
`url_variables`	Array of objects	URL variables for interpolation
`url_variables[].key` Required	String	Name of the variable Example: `token`
`url_variables[].value` Required	String	Value of the variable Example: `123`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesHook
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Delete a system hook

DELETE /api/v4/hooks/{hook_id}

Deletes a specified system hook. Administrators only.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the system hook

Responses

Code	Description	Schema
`200`	OK	APIEntitiesHook
`400`	Bad Request	—
`404`	Not found	—

Update a custom header

PUT /api/v4/hooks/{hook_id}/custom_headers/{key}

Updates a custom header for a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The name of the custom header

Request body (application/json)

Property	Type	Description
`value` Required	String	The value of the custom header

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Delete a custom header

DELETE /api/v4/hooks/{hook_id}/custom_headers/{key}

Deletes a custom header from a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The name of the custom header

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

Update a URL variable

PUT /api/v4/hooks/{hook_id}/url_variables/{key}

Updates a URL variable for a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The key of the variable

Request body (application/json)

Property	Type	Description
`value` Required	String	The value of the variable

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Delete a URL variable

DELETE /api/v4/hooks/{hook_id}/url_variables/{key}

Deletes a URL variable from a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The key of the variable

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

List all webhooks for a project

GET /api/v4/projects/{id}/hooks

Lists all webhooks for a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`page` Query	Integer	Current page number Default: `1` Example: `1`
`per_page` Query	Integer	Number of items per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectHook
`400`	Bad Request	—
`404`	Not Found	—

Add a webhook to a project

POST /api/v4/projects/{id}/hooks

Adds a webhook to a specified project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches` Allowed values: `wildcard`, `regex`, `all_branches`
`confidential_issues_events`	Boolean	Trigger hook on confidential issues events
`confidential_note_events`	Boolean	Trigger hook on confidential note (comment) events
`custom_headers`	Array of objects	Custom headers
`custom_headers[].key` Required	String	Name of the header Example: `X-Custom-Header`
`custom_headers[].value` Required	String	Value of the header Example: `value`
`custom_webhook_template`	String	Custom template for the request payload
`deployment_events`	Boolean	Trigger hook on deployment events
`description`	String	Description of the hook
`duo_flow_callback_enabled`	Boolean	Allow Duo Agent Platform flows to send lifecycle and progress events to this webhook. A flow must reference this webhook’s ID as callback_hook_id when it starts
`emoji_events`	Boolean	Trigger hook on emoji events
`enable_ssl_verification`	Boolean	Do SSL verification when triggering the hook
`feature_flag_events`	Boolean	Trigger hook on feature flag events
`issues_events`	Boolean	Trigger hook on issues events
`job_events`	Boolean	Trigger hook on job events
`merge_requests_events`	Boolean	Trigger hook on merge request events
`milestone_events`	Boolean	Trigger hook on milestone events
`name`	String	Name of the hook
`note_events`	Boolean	Trigger hook on note (comment) events
`pipeline_events`	Boolean	Trigger hook on pipeline events
`push_events`	Boolean	Trigger hook on push events
`push_events_branch_filter`	String	Trigger hook on specified branch only
`releases_events`	Boolean	Trigger hook on release events
`resource_access_token_events`	Boolean	Trigger hook on project access token expiry events
`resource_deploy_token_events`	Boolean	Trigger hook on deploy token expiry events
`signing_token`	String	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	Trigger hook on tag push events
`token`	String	Secret token to validate received payloads; this will not be returned in the response
`url` Required	String	The URL to send the request to Example: `http://example.com/hook`
`url_variables`	Array of objects	URL variables for interpolation
`url_variables[].key` Required	String	Name of the variable Example: `token`
`url_variables[].value` Required	String	Value of the variable Example: `123`
`vulnerability_events`	Boolean	Trigger hook on vulnerability events
`wiki_page_events`	Boolean	Trigger hook on wiki events

Responses

Code	Description	Schema
`201`	Created	APIEntitiesProjectHook
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Retrieve a project webhook

GET /api/v4/projects/{id}/hooks/{hook_id}

Retrieves a specified webhook for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`hook_id` Path, required	Integer	The ID of a project hook

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectHook
`400`	Bad Request	—
`404`	Not found	—

Update a project webhook

PUT /api/v4/projects/{id}/hooks/{hook_id}

Updates a specified webhook for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`hook_id` Path, required	Integer	The ID of the project hook

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches` Allowed values: `wildcard`, `regex`, `all_branches`
`confidential_issues_events`	Boolean	Trigger hook on confidential issues events
`confidential_note_events`	Boolean	Trigger hook on confidential note (comment) events
`custom_headers`	Array of objects	Custom headers
`custom_headers[].key` Required	String	Name of the header Example: `X-Custom-Header`
`custom_headers[].value` Required	String	Value of the header Example: `value`
`custom_webhook_template`	String	Custom template for the request payload
`deployment_events`	Boolean	Trigger hook on deployment events
`description`	String	Description of the hook
`duo_flow_callback_enabled`	Boolean	Allow Duo Agent Platform flows to send lifecycle and progress events to this webhook. A flow must reference this webhook’s ID as callback_hook_id when it starts
`emoji_events`	Boolean	Trigger hook on emoji events
`enable_ssl_verification`	Boolean	Do SSL verification when triggering the hook
`feature_flag_events`	Boolean	Trigger hook on feature flag events
`issues_events`	Boolean	Trigger hook on issues events
`job_events`	Boolean	Trigger hook on job events
`merge_requests_events`	Boolean	Trigger hook on merge request events
`milestone_events`	Boolean	Trigger hook on milestone events
`name`	String	Name of the hook
`note_events`	Boolean	Trigger hook on note (comment) events
`pipeline_events`	Boolean	Trigger hook on pipeline events
`push_events`	Boolean	Trigger hook on push events
`push_events_branch_filter`	String	Trigger hook on specified branch only
`releases_events`	Boolean	Trigger hook on release events
`resource_access_token_events`	Boolean	Trigger hook on project access token expiry events
`resource_deploy_token_events`	Boolean	Trigger hook on deploy token expiry events
`signing_token`	String	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	Trigger hook on tag push events
`token`	String	Secret token to validate received payloads; this will not be returned in the response
`url`	String	The URL to send the request to
`url_variables`	Array of objects	URL variables for interpolation
`url_variables[].key` Required	String	Name of the variable Example: `token`
`url_variables[].value` Required	String	Value of the variable Example: `123`
`vulnerability_events`	Boolean	Trigger hook on vulnerability events
`wiki_page_events`	Boolean	Trigger hook on wiki events

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectHook
`400`	Validation error	—
`404`	Not found	—
`422`	Unprocessable entity	—

Delete a project webhook

DELETE /api/v4/projects/{id}/hooks/{hook_id}

Deletes a specified webhook for a project.

Parameters

Name	Type	Description
`id` Path, required	String or integer	The ID or URL-encoded path of the project
`hook_id` Path, required	Integer	The ID of the project hook

Responses

Code	Description	Schema
`200`	OK	APIEntitiesProjectHook
`400`	Bad Request	—
`404`	Not found	—

Update a custom header

PUT /api/v4/projects/{id}/hooks/{hook_id}/custom_headers/{key}

Updates a custom header for a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The name of the custom header
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`value` Required	String	The value of the custom header

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Delete a custom header

DELETE /api/v4/projects/{id}/hooks/{hook_id}/custom_headers/{key}

Deletes a custom header from a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The name of the custom header
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

List all events

GET /api/v4/projects/{id}/hooks/{hook_id}/events

Lists all events for a specified webhook.

Parameters

Name	Type	Description
`status` Query	Array of strings	HTTP status code of the event
`per_page` Query	Integer	Number of items per page Default: `20` Maximum: `20` Minimum: `1` Example: `20`
`page` Query	Integer	Current page number Default: `1` Example: `1`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`
`hook_id` Path, required	Integer	The ID of the hook

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad request	—
`403`	Forbidden	—
`404`	Not found	—

Resend a webhook event

POST /api/v4/projects/{id}/hooks/{hook_id}/events/{hook_log_id}/resend

Resends a webhook event. This endpoint has a rate limit of five requests per minute for each authenticated user for a given project or group. On GitLab Self-Managed and GitLab Dedicated, an administrator can change this limit in the application settings.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`hook_log_id` Path, required	Integer	The ID of the hook log entry
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad Request	—
`404`	Not found	—
`422`	Unprocessable entity	—
`429`	Too many requests	—

Trigger a test webhook

POST /api/v4/projects/{id}/hooks/{hook_id}/test/{trigger}

Triggers a test webhook. This endpoint has a rate limit of five requests per minute for each authenticated user for a given project or group. On GitLab Self-Managed and GitLab Dedicated, an administrator can change this limit in the application settings.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`trigger` Path, required	String	The type of trigger hook Allowed values: `confidential_issues_events`, `confidential_note_events`, `deployment_events`, `emoji_events`, `feature_flag_events`, `issues_events`, `job_events`, `merge_requests_events`, `milestone_events`, `note_events`, `pipeline_events`, `push_events`, `releases_events`, `resource_access_token_events`, `resource_deploy_token_events`, `tag_push_events`, `wiki_page_events` Minimum length: `1`
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`201`	Created	—
`400`	Bad request	—
`403`	Forbidden	—
`404`	Not found	—
`422`	Unprocessable entity	—
`429`	Too many requests	—

Update a URL variable

PUT /api/v4/projects/{id}/hooks/{hook_id}/url_variables/{key}

Updates a URL variable for a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The key of the variable
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Request body (application/json)

Property	Type	Description
`value` Required	String	The value of the variable

Responses

Code	Description	Schema
`200`	OK	—
`400`	Bad Request	—
`404`	Not Found	—

Delete a URL variable

DELETE /api/v4/projects/{id}/hooks/{hook_id}/url_variables/{key}

Deletes a URL variable from a specified webhook.

Parameters

Name	Type	Description
`hook_id` Path, required	Integer	The ID of the hook
`key` Path, required	String	The key of the variable
`id` Path, required	String or integer	The ID or URL-encoded path of the project Example: `11`

Responses

Code	Description	Schema
`204`	No Content	—
`400`	Bad Request	—
`404`	Not Found	—

Schemas

Objects returned by the operations above and objects nested in their request bodies.

APIEntitiesHook

Property	Type	Description
`alert_status`	String	Example: `:executable`
`branch_filter_strategy`	String	Example: `wildcard`
`created_at`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`custom_headers`	Array of objects	Example: `[{"X-Custom-Header":"value"}]`
`custom_webhook_template`	String	Example: `{"event":"{{object_kind}}"}`
`description`	String	Example: `Hook description`
`disabled_until`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`enable_ssl_verification`	Boolean	—
`id`	Integer (int64)	Example: `1`
`merge_requests_events`	Boolean	—
`name`	String	Example: `Hook name`
`organization_id`	Integer	Example: `1`
`push_events`	Boolean	—
`push_events_branch_filter`	String	Example: `my-branch-*`
`repository_update_events`	Boolean	—
`signing_token_present`	Boolean	Whether an HMAC signing token is configured Example: `false`
`tag_push_events`	Boolean	—
`token_present`	Boolean	Whether a secret token is configured Example: `false`
`url`	String	Example: `https://webhook.site`
`url_variables`	Array of objects	Example: `[{"token":"secr3t"}]`

APIEntitiesProjectHook

Property	Type	Description
`alert_status`	String	Example: `:executable`
`branch_filter_strategy`	String	Example: `wildcard`
`confidential_issues_events`	Boolean	—
`confidential_note_events`	Boolean	—
`created_at`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`custom_headers`	Array of objects	Example: `[{"X-Custom-Header":"value"}]`
`custom_webhook_template`	String	Example: `{"event":"{{object_kind}}"}`
`deployment_events`	Boolean	—
`description`	String	Example: `Hook description`
`disabled_until`	String (date-time)	Example: `2012-05-28T04:42:42-07:00`
`duo_flow_callback_enabled`	Boolean	—
`emoji_events`	Boolean	—
`enable_ssl_verification`	Boolean	—
`feature_flag_events`	Boolean	—
`id`	Integer (int64)	Example: `1`
`issues_events`	Boolean	—
`job_events`	Boolean	—
`merge_requests_events`	Boolean	—
`milestone_events`	Boolean	—
`name`	String	Example: `Hook name`
`note_events`	Boolean	—
`organization_id`	Integer	Example: `1`
`pipeline_events`	Boolean	—
`project_id`	Integer (int64)	Example: `1`
`push_events`	Boolean	—
`push_events_branch_filter`	String	Example: `my-branch-*`
`releases_events`	Boolean	—
`repository_update_events`	Boolean	—
`resource_access_token_events`	Boolean	—
`resource_deploy_token_events`	Boolean	—
`signing_token_present`	Boolean	Whether an HMAC signing token is configured Example: `false`
`tag_push_events`	Boolean	—
`token_present`	Boolean	Whether a secret token is configured Example: `false`
`url`	String	Example: `https://webhook.site`
`url_variables`	Array of objects	Example: `[{"token":"secr3t"}]`
`vulnerability_events`	Boolean	—
`wiki_page_events`	Boolean	—

List all system hooks

Create a system hook

Retrieve a system hook

Create a test run

Update a system hook

Delete a system hook

Update a custom header

Delete a custom header

Update a URL variable

Delete a URL variable

List all webhooks for a project

Add a webhook to a project

Retrieve a project webhook

Update a project webhook

Delete a project webhook

Update a custom header

Delete a custom header

List all events

Resend a webhook event

Trigger a test webhook

Update a URL variable

Delete a URL variable

Schemas

APIEntitiesHook

APIEntitiesProjectHook

Request trial access

Thank you

Error

Request callback

Thank you

Something went wrong

Book your sessions

Thank you

Error

Request demo

Thank you

Error

Get the PCI SSC Compliance Report

Thank you

Error