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	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of 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. Defaults to `wildcard` Allowed values: `wildcard`, `regex`, `all_branches`
`custom_headers`	Array of objects	Custom headers for the hook
`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 system hook request payload
`description`	String	Description of the hook. Introduced in GitLab 17.1
`enable_ssl_verification`	Boolean	If `true`, verifies the SSL certificate when the hook is triggered
`merge_requests_events`	Boolean	If `true`, triggers the system hook on merge request events
`name`	String	Name of the hook. Introduced in GitLab 17.1
`push_events`	Boolean	If `true`, triggers the system hook on push events
`push_events_branch_filter`	String	Filter push events by branch name
`repository_update_events`	Boolean	If `true`, triggers the system 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, and is not returned in the response. Introduced in GitLab 19.0
`tag_push_events`	Boolean	If `true`, triggers the system hook on tag push events
`token`	String	Secret token used to validate received payloads. Not returned in the response, and changing the hook URL resets it
`url` Required	String	Webhook URL 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	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	ID of the system 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	ID of the system hook

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Defaults to `wildcard` Allowed values: `wildcard`, `regex`, `all_branches`
`custom_headers`	Array of objects	Custom headers for the hook
`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 system hook request payload
`description`	String	Description of the hook. Introduced in GitLab 17.1
`enable_ssl_verification`	Boolean	If `true`, verifies the SSL certificate when the hook is triggered
`merge_requests_events`	Boolean	If `true`, triggers the system hook on merge request events
`name`	String	Name of the hook. Introduced in GitLab 17.1
`push_events`	Boolean	If `true`, triggers the system hook on push events
`push_events_branch_filter`	String	Filter push events by branch name
`repository_update_events`	Boolean	If `true`, triggers the system 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, and is not returned in the response. Introduced in GitLab 19.0
`tag_push_events`	Boolean	If `true`, triggers the system hook on tag push events
`token`	String	Secret token used to validate received payloads. Not returned in the response, and changing the hook URL resets it
`url`	String	Webhook URL
`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	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	ID of the hook
`key` Path, required	String	Name of the custom header

Request body (application/json)

Property	Type	Description
`value` Required	String	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	ID of the hook
`key` Path, required	String	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	ID of the hook
`key` Path, required	String	Key of the URL variable

Request body (application/json)

Property	Type	Description
`value` Required	String	Value of the URL 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	ID of the hook
`key` Path, required	String	Key of the URL 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	ID or URL-encoded path of the project
`page` Query	Integer	Page number of results to retrieve Default: `1` Example: `1`
`per_page` Query	Integer	Number of items to list per page Default: `20` Example: `20`

Responses

Code	Description	Schema
`200`	OK	Array of 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	ID or URL-encoded path of the project

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Defaults to `wildcard` Allowed values: `wildcard`, `regex`, `all_branches`
`confidential_issues_events`	Boolean	If `true`, triggers the project webhook on confidential issue events
`confidential_note_events`	Boolean	If `true`, triggers the project webhook on confidential note events
`custom_headers`	Array of objects	Custom headers for the hook
`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 webhook request payload
`deployment_events`	Boolean	If `true`, triggers the project webhook on deployment events
`description`	String	Description of the project webhook. Introduced in GitLab 17.1
`duo_flow_callback_enabled`	Boolean	If `true`, allows Duo Agent Platform flows to send lifecycle and progress events to this project webhook. A flow must reference the webhook’s ID as `callback_hook_id` when it starts. Introduced in GitLab 19.4 with a feature flag named `duo_flow_callback_hooks`. Disabled by default
`emoji_events`	Boolean	If `true`, triggers the project webhook on emoji events
`enable_ssl_verification`	Boolean	If `true`, verifies the SSL certificate when the webhook is triggered
`feature_flag_events`	Boolean	If `true`, triggers the project webhook on feature flag events
`issues_events`	Boolean	If `true`, triggers the project webhook on issue events
`job_events`	Boolean	If `true`, triggers the project webhook on job events
`merge_requests_events`	Boolean	If `true`, triggers the project webhook on merge request events
`milestone_events`	Boolean	If `true`, triggers the project webhook on milestone events
`name`	String	Name of the project webhook. Introduced in GitLab 17.1
`note_events`	Boolean	If `true`, triggers the project webhook on note events
`pipeline_events`	Boolean	If `true`, triggers the project webhook on pipeline events
`push_events`	Boolean	If `true`, triggers the project webhook on push events
`push_events_branch_filter`	String	Filter push events by branch name
`releases_events`	Boolean	If `true`, triggers the project webhook on release events
`resource_access_token_events`	Boolean	If `true`, triggers the project webhook on project access token expiry events
`resource_deploy_token_events`	Boolean	If `true`, triggers the project webhook on project 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, and is not returned in the response. Introduced in GitLab 19.0
`tag_push_events`	Boolean	If `true`, triggers the project webhook on tag push events
`token`	String	Secret token used to validate received payloads. Not returned in the response, and changing the webhook URL resets it
`url` Required	String	Webhook URL 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	If `true`, triggers the project webhook on vulnerability events
`wiki_page_events`	Boolean	If `true`, triggers the project webhook on wiki page 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	ID or URL-encoded path of the project
`hook_id` Path, required	Integer	ID of the project webhook

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	ID or URL-encoded path of the project
`hook_id` Path, required	Integer	ID of the project webhook

Request body (application/json)

Property	Type	Description
`branch_filter_strategy`	String	Filter push events by branch. Defaults to `wildcard` Allowed values: `wildcard`, `regex`, `all_branches`
`confidential_issues_events`	Boolean	If `true`, triggers the project webhook on confidential issue events
`confidential_note_events`	Boolean	If `true`, triggers the project webhook on confidential note events
`custom_headers`	Array of objects	Custom headers for the hook
`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 webhook request payload
`deployment_events`	Boolean	If `true`, triggers the project webhook on deployment events
`description`	String	Description of the project webhook. Introduced in GitLab 17.1
`duo_flow_callback_enabled`	Boolean	If `true`, allows Duo Agent Platform flows to send lifecycle and progress events to this project webhook. A flow must reference the webhook’s ID as `callback_hook_id` when it starts. Introduced in GitLab 19.4 with a feature flag named `duo_flow_callback_hooks`. Disabled by default
`emoji_events`	Boolean	If `true`, triggers the project webhook on emoji events
`enable_ssl_verification`	Boolean	If `true`, verifies the SSL certificate when the webhook is triggered
`feature_flag_events`	Boolean	If `true`, triggers the project webhook on feature flag events
`issues_events`	Boolean	If `true`, triggers the project webhook on issue events
`job_events`	Boolean	If `true`, triggers the project webhook on job events
`merge_requests_events`	Boolean	If `true`, triggers the project webhook on merge request events
`milestone_events`	Boolean	If `true`, triggers the project webhook on milestone events
`name`	String	Name of the project webhook. Introduced in GitLab 17.1
`note_events`	Boolean	If `true`, triggers the project webhook on note events
`pipeline_events`	Boolean	If `true`, triggers the project webhook on pipeline events
`push_events`	Boolean	If `true`, triggers the project webhook on push events
`push_events_branch_filter`	String	Filter push events by branch name
`releases_events`	Boolean	If `true`, triggers the project webhook on release events
`resource_access_token_events`	Boolean	If `true`, triggers the project webhook on project access token expiry events
`resource_deploy_token_events`	Boolean	If `true`, triggers the project webhook on project 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, and is not returned in the response. Introduced in GitLab 19.0
`tag_push_events`	Boolean	If `true`, triggers the project webhook on tag push events
`token`	String	Secret token used to validate received payloads. Not returned in the response, and changing the webhook URL resets it
`url`	String	Webhook URL
`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	If `true`, triggers the project webhook on vulnerability events
`wiki_page_events`	Boolean	If `true`, triggers the project webhook on wiki page 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	ID or URL-encoded path of the project
`hook_id` Path, required	Integer	ID of the project webhook

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	ID of the hook
`key` Path, required	String	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	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	ID of the hook
`key` Path, required	String	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	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)
`per_page` Query	Integer	Number of items to list per page Default: `20` Maximum: `20` Minimum: `1` Example: `20`
`page` Query	Integer	Page number of results to retrieve 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	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	ID of the hook
`hook_log_id` Path, required	Integer	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	ID of the hook
`trigger` Path, required	String	Type of webhook event to test 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	ID of the hook
`key` Path, required	String	Key of the URL 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	Value of the URL 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	ID of the hook
`key` Path, required	String	Key of the URL 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

Request partner program details

Request received

Error