Documentation
Documentation
https://docs.gitlab.com/api/
APIReference
https://docs.gitlab.com/api/api_resources/
Authentication
https://docs.gitlab.com/api/rest/authentication/
OpenAPI Specification
swagger: '2.0'
info:
title: GitLab access_requests hooks API
version: v4
description: Operations related to access requests
host: gitlab.com
produces:
- application/json
tags:
- name: hooks
description: Operations about hooks
paths:
/api/v4/projects/{id}/hooks/{hook_id}/url_variables/{key}:
put:
summary: Set a url variable
description: Sets a URL variable for a webhook
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The key of the variable
type: string
required: true
- in: path
name: id
type: integer
format: int32
required: true
- name: putApiV4ProjectsIdHooksHookIdUrlVariablesKey
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdHooksHookIdUrlVariablesKey'
responses:
'200':
description: Set a url variable
tags:
- hooks
operationId: putApiV4ProjectsIdHooksHookIdUrlVariablesKey
delete:
summary: Un-Set a url variable
description: Removes a URL variable from a webhook
produces:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The key of the variable
type: string
required: true
- in: path
name: id
type: integer
format: int32
required: true
responses:
'204':
description: Un-Set a url variable
tags:
- hooks
operationId: deleteApiV4ProjectsIdHooksHookIdUrlVariablesKey
/api/v4/projects/{id}/hooks/{hook_id}/custom_headers/{key}:
put:
summary: Set a custom header
description: Sets a custom header for a webhook
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The name of the custom header
type: string
required: true
- in: path
name: id
type: integer
format: int32
required: true
- name: putApiV4ProjectsIdHooksHookIdCustomHeadersKey
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdHooksHookIdCustomHeadersKey'
responses:
'200':
description: Set a custom header
tags:
- hooks
operationId: putApiV4ProjectsIdHooksHookIdCustomHeadersKey
delete:
summary: Un-Set a custom header
description: Removes a custom header from a webhook
produces:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The name of the custom header
type: string
required: true
- in: path
name: id
type: integer
format: int32
required: true
responses:
'204':
description: Un-Set a custom header
tags:
- hooks
operationId: deleteApiV4ProjectsIdHooksHookIdCustomHeadersKey
/api/v4/projects/{id}/hooks:
get:
summary: List project hooks
description: Get a list of project hooks
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List project hooks
schema:
type: array
items:
$ref: '#/definitions/API_Entities_ProjectHook'
tags:
- hooks
operationId: getApiV4ProjectsIdHooks
post:
summary: Add project hook
description: Adds a hook to a specified project
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- name: postApiV4ProjectsIdHooks
in: body
required: true
schema:
$ref: '#/definitions/postApiV4ProjectsIdHooks'
responses:
'201':
description: Add project hook
schema:
$ref: '#/definitions/API_Entities_ProjectHook'
'400':
description: Validation error
'404':
description: Not found
'422':
description: Unprocessable entity
tags:
- hooks
operationId: postApiV4ProjectsIdHooks
/api/v4/projects/{id}/hooks/{hook_id}:
get:
summary: Get project hook
description: Get a specific hook for a project
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: hook_id
description: The ID of a project hook
type: integer
format: int32
required: true
responses:
'200':
description: Get project hook
schema:
$ref: '#/definitions/API_Entities_ProjectHook'
'404':
description: Not found
tags:
- hooks
operationId: getApiV4ProjectsIdHooksHookId
put:
summary: Edit project hook
description: Edits a hook for a specified project.
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: hook_id
description: The ID of the project hook
type: integer
format: int32
required: true
- name: putApiV4ProjectsIdHooksHookId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4ProjectsIdHooksHookId'
responses:
'200':
description: Edit project hook
schema:
$ref: '#/definitions/API_Entities_ProjectHook'
'400':
description: Validation error
'404':
description: Not found
'422':
description: Unprocessable entity
tags:
- hooks
operationId: putApiV4ProjectsIdHooksHookId
delete:
summary: Delete a project hook
description: Removes a hook from a project. This is an idempotent method and can be called multiple times. Either the hook is available or not.
produces:
- application/json
parameters:
- in: path
name: id
description: The ID or URL-encoded path of the project
type: string
required: true
- in: path
name: hook_id
description: The ID of the project hook
type: integer
format: int32
required: true
responses:
'204':
description: Not found
tags:
- hooks
operationId: deleteApiV4ProjectsIdHooksHookId
/api/v4/projects/{id}/hooks/{hook_id}/events:
get:
summary: Get events for a given hook id
description: List web hook logs by hook id
produces:
- application/json
parameters:
- in: query
name: status
description: HTTP status code of the event
type: array
items:
type: string
enum:
- '100'
- '101'
- '102'
- '103'
- '200'
- '201'
- '202'
- '203'
- '204'
- '205'
- '206'
- '207'
- '208'
- '226'
- '300'
- '301'
- '302'
- '303'
- '304'
- '305'
- '306'
- '307'
- '308'
- '400'
- '401'
- '402'
- '403'
- '404'
- '405'
- '406'
- '407'
- '408'
- '409'
- '410'
- '411'
- '412'
- '413'
- '414'
- '415'
- '416'
- '417'
- '421'
- '422'
- '423'
- '424'
- '425'
- '426'
- '428'
- '429'
- '431'
- '451'
- '500'
- '501'
- '502'
- '503'
- '504'
- '505'
- '506'
- '507'
- '508'
- '509'
- '510'
- '511'
- successful
- client_failure
- server_failure
required: false
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
minimum: 1
maximum: 20
required: false
example: 20
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: path
name: id
type: integer
format: int32
required: true
- in: path
name: hook_id
type: integer
format: int32
required: true
responses:
'200':
description: Get events for a given hook id
'400':
description: Bad request
'404':
description: Not found
'403':
description: Forbidden
tags:
- hooks
operationId: getApiV4ProjectsIdHooksHookIdEvents
/api/v4/projects/{id}/hooks/{hook_id}/test/{trigger}:
post:
summary: Triggers a hook test
description: Triggers a hook test
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: trigger
description: The type of trigger hook
type: string
enum:
- 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
- vulnerability_events
required: true
- in: path
name: id
type: integer
format: int32
required: true
responses:
'201':
description: Triggers a hook test
'400':
description: Bad request
'404':
description: Not found
'422':
description: Unprocessable entity
'429':
description: Too many requests
tags:
- hooks
operationId: postApiV4ProjectsIdHooksHookIdTestTrigger
/api/v4/projects/{id}/hooks/{hook_id}/events/{hook_log_id}/resend:
post:
summary: Resend a webhook event
description: Resend a webhook event
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: id
type: integer
format: int32
required: true
- in: path
name: hook_id
type: integer
format: int32
required: true
- in: path
name: hook_log_id
type: integer
format: int32
required: true
responses:
'201':
description: Resend a webhook event
'422':
description: Unprocessable entity
'404':
description: Not found
'429':
description: Too many requests
tags:
- hooks
operationId: postApiV4ProjectsIdHooksHookIdEventsHookLogIdResend
/api/v4/hooks/{hook_id}/url_variables/{key}:
put:
summary: Set a url variable
description: Sets a URL variable for a webhook
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The key of the variable
type: string
required: true
- name: putApiV4HooksHookIdUrlVariablesKey
in: body
required: true
schema:
$ref: '#/definitions/putApiV4HooksHookIdUrlVariablesKey'
responses:
'200':
description: Set a url variable
tags:
- hooks
operationId: putApiV4HooksHookIdUrlVariablesKey
delete:
summary: Un-Set a url variable
description: Removes a URL variable from a webhook
produces:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The key of the variable
type: string
required: true
responses:
'204':
description: Un-Set a url variable
tags:
- hooks
operationId: deleteApiV4HooksHookIdUrlVariablesKey
/api/v4/hooks/{hook_id}/custom_headers/{key}:
put:
summary: Set a custom header
description: Sets a custom header for a webhook
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The name of the custom header
type: string
required: true
- name: putApiV4HooksHookIdCustomHeadersKey
in: body
required: true
schema:
$ref: '#/definitions/putApiV4HooksHookIdCustomHeadersKey'
responses:
'200':
description: Set a custom header
tags:
- hooks
operationId: putApiV4HooksHookIdCustomHeadersKey
delete:
summary: Un-Set a custom header
description: Removes a custom header from a webhook
produces:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
- in: path
name: key
description: The name of the custom header
type: string
required: true
responses:
'204':
description: Un-Set a custom header
tags:
- hooks
operationId: deleteApiV4HooksHookIdCustomHeadersKey
/api/v4/hooks:
get:
summary: List system hooks
description: Get a list of all system hooks
produces:
- application/json
parameters:
- in: query
name: page
description: Current page number
type: integer
format: int32
default: 1
required: false
example: 1
- in: query
name: per_page
description: Number of items per page
type: integer
format: int32
default: 20
required: false
example: 20
responses:
'200':
description: List system hooks
schema:
type: array
items:
$ref: '#/definitions/API_Entities_Hook'
tags:
- hooks
operationId: getApiV4Hooks
post:
summary: Add new system hook
description: Add a new system hook
produces:
- application/json
consumes:
- application/json
parameters:
- name: postApiV4Hooks
in: body
required: true
schema:
$ref: '#/definitions/postApiV4Hooks'
responses:
'201':
description: Add new system hook
schema:
$ref: '#/definitions/API_Entities_Hook'
'400':
description: Validation error
'404':
description: Not found
'422':
description: Unprocessable entity
tags:
- hooks
operationId: postApiV4Hooks
/api/v4/hooks/{hook_id}:
get:
summary: Get system hook
description: Get a system hook by its ID. Introduced in GitLab 14.9.
produces:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the system hook
type: integer
format: int32
required: true
responses:
'200':
description: Get system hook
schema:
$ref: '#/definitions/API_Entities_Hook'
'404':
description: Not found
tags:
- hooks
operationId: getApiV4HooksHookId
put:
summary: Edit system hook
description: Edits a system hook
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the system hook
type: integer
format: int32
required: true
- name: putApiV4HooksHookId
in: body
required: true
schema:
$ref: '#/definitions/putApiV4HooksHookId'
responses:
'200':
description: Edit system hook
schema:
$ref: '#/definitions/API_Entities_Hook'
'400':
description: Validation error
'404':
description: Not found
'422':
description: Unprocessable entity
tags:
- hooks
operationId: putApiV4HooksHookId
post:
summary: Test a hook
description: Tests a webhook by triggering a test event
produces:
- application/json
consumes:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the hook
type: integer
format: int32
required: true
responses:
'201':
description: Test a hook
tags:
- hooks
operationId: postApiV4HooksHookId
delete:
summary: Delete system hook
description: Deletes a system hook
produces:
- application/json
parameters:
- in: path
name: hook_id
description: The ID of the system hook
type: integer
format: int32
required: true
responses:
'404':
description: Not found
'204':
description: Delete system hook
schema:
$ref: '#/definitions/API_Entities_Hook'
tags:
- hooks
operationId: deleteApiV4HooksHookId
definitions:
API_Entities_Hook:
type: object
properties:
id:
type: integer
format: int32
example: 1
url:
type: string
example: https://webhook.site
name:
type: string
example: Hook name
description:
type: string
example: Hook description
created_at:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
push_events:
type: boolean
tag_push_events:
type: boolean
merge_requests_events:
type: boolean
repository_update_events:
type: boolean
enable_ssl_verification:
type: boolean
organization_id:
type: integer
format: int32
example: 1
alert_status:
type: string
example: executable
disabled_until:
type: string
format: date-time
example: '2012-05-28T04:42:42-07:00'
url_variables:
type: array
items:
type: object
example:
- token: secr3t
push_events_branch_filter:
type: string
example: my-branch-*
branch_filter_strategy:
type: string
example: wildcard
custom_webhook_template:
type: string
example: '{"event":"{{object_kind}}"}'
custom_headers:
type: array
items:
type: object
example:
- X-Custom-Header: value
token_present:
type: boolean
example: false
description: Whether a secret token is configured
signing_token_present:
type: boolean
example: false
description: Whether an HMAC signing token is configured
required:
- id
- url
- name
- description
- created_at
- push_events
- tag_push_events
- merge_requests_events
- repository_update_events
- enable_ssl_verification
- alert_status
- disabled_until
- push_events_branch_filter
- branch_filter_strategy
- custom_webhook_template
- token_present
- signing_token_present
description: API_Entities_Hook model
postApiV4ProjectsIdHooks:
type: object
properties:
url:
type: string
description: The URL to send the request to
example: http://example.com/hook
name:
type: string
description: Name of the hook
description:
type: string
description: Description of the hook
push_events:
type: boolean
description: Trigger hook on push events
issues_events:
type: boolean
description: Trigger hook on issues events
confidential_issues_events:
type: boolean
description: Trigger hook on confidential issues events
merge_requests_events:
type: boolean
description: Trigger hook on merge request events
tag_push_events:
type: boolean
description: Trigger hook on tag push events
note_events:
type: boolean
description: Trigger hook on note (comment) events
confidential_note_events:
type: boolean
description: Trigger hook on confidential note (comment) events
job_events:
type: boolean
description: Trigger hook on job events
pipeline_events:
type: boolean
description: Trigger hook on pipeline events
wiki_page_events:
type: boolean
description: Trigger hook on wiki events
deployment_events:
type: boolean
description: Trigger hook on deployment events
feature_flag_events:
type: boolean
description: Trigger hook on feature flag events
releases_events:
type: boolean
description: Trigger hook on release events
milestone_events:
type: boolean
description: Trigger hook on milestone events
emoji_events:
type: boolean
description: Trigger hook on emoji events
resource_access_token_events:
type: boolean
description: Trigger hook on project access token expiry events
resource_deploy_token_events:
type: boolean
description: Trigger hook on deploy token expiry events
enable_ssl_verification:
type: boolean
description: Do SSL verification when triggering the hook
token:
type: string
description: Secret token to validate received payloads; this will not be returned in the response
signing_token:
type: string
description: 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
push_events_branch_filter:
type: string
description: Trigger hook on specified branch only
custom_webhook_template:
type: string
description: Custom template for the request payload
branch_filter_strategy:
type: string
description: Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches`
enum:
- wildcard
- regex
- all_branches
vulnerability_events:
type: boolean
description: Trigger hook on vulnerability events
url_variables:
type: array
description: URL variables for interpolation
items:
type: object
properties:
key:
type: string
description: Name of the variable
example: token
value:
type: string
description: Value of the variable
example: '123'
required:
- key
- value
custom_headers:
type: array
description: Custom headers
items:
type: object
properties:
key:
type: string
description: Name of the header
example: X-Custom-Header
value:
type: string
description: Value of the header
example: value
required:
- key
- value
required:
- url
description: Add project hook
postApiV4Hooks:
type: object
properties:
url:
type: string
description: The URL to send the request to
example: http://example.com/hook
name:
type: string
description: Name of the hook
description:
type: string
description: Description of the hook
token:
type: string
description: Secret token to validate received payloads; this isn't returned in the response
signing_token:
type: string
description: 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
push_events:
type: boolean
description: When true, the hook fires on push events
tag_push_events:
type: boolean
description: When true, the hook fires on new tags being pushed
merge_requests_events:
type: boolean
description: Trigger hook on merge requests events
repository_update_events:
type: boolean
description: Trigger hook on repository update events
enable_ssl_verification:
type: boolean
description: Do SSL verification when triggering the hook
push_events_branch_filter:
type: string
description: Trigger hook on specified branch only
branch_filter_strategy:
type: string
description: Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches`
enum:
- wildcard
- regex
- all_branches
custom_webhook_template:
type: string
description: Custom template for the request payload
url_variables:
type: array
description: URL variables for interpolation
items:
type: object
properties:
key:
type: string
description: Name of the variable
example: token
value:
type: string
description: Value of the variable
example: '123'
required:
- key
- value
custom_headers:
type: array
description: Custom headers
items:
type: object
properties:
key:
type: string
description: Name of the header
example: X-Custom-Header
value:
type: string
description: Value of the header
example: value
required:
- key
- value
required:
- url
description: Add new system hook
putApiV4HooksHookIdUrlVariablesKey:
type: object
properties:
value:
type: string
description: The value of the variable
required:
- value
description: Set a url variable
putApiV4ProjectsIdHooksHookId:
type: object
properties:
url:
type: string
description: The URL to send the request to
name:
type: string
description: Name of the hook
description:
type: string
description: Description of the hook
push_events:
type: boolean
description: Trigger hook on push events
issues_events:
type: boolean
description: Trigger hook on issues events
confidential_issues_events:
type: boolean
description: Trigger hook on confidential issues events
merge_requests_events:
type: boolean
description: Trigger hook on merge request events
tag_push_events:
type: boolean
description: Trigger hook on tag push events
note_events:
type: boolean
description: Trigger hook on note (comment) events
confidential_note_events:
type: boolean
description: Trigger hook on confidential note (comment) events
job_events:
type: boolean
description: Trigger hook on job events
pipeline_events:
type: boolean
description: Trigger hook on pipeline events
wiki_page_events:
type: boolean
description: Trigger hook on wiki events
deployment_events:
type: boolean
description: Trigger hook on deployment events
feature_flag_events:
type: boolean
description: Trigger hook on feature flag events
releases_events:
type: boolean
description: Trigger hook on release events
milestone_events:
type: boolean
description: Trigger hook on milestone events
emoji_events:
type: boolean
description: Trigger hook on emoji events
resource_access_token_events:
type: boolean
description: Trigger hook on project access token expiry events
resource_deploy_token_events:
type: boolean
description: Trigger hook on deploy token expiry events
enable_ssl_verification:
type: boolean
description: Do SSL verification when triggering the hook
token:
type: string
description: Secret token to validate received payloads; this will not be returned in the response
signing_token:
type: string
description: 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
push_events_branch_filter:
type: string
description: Trigger hook on specified branch only
custom_webhook_template:
type: string
description: Custom template for the request payload
branch_filter_strategy:
type: string
description: Filter push events by branch. Possible values are `wildcard` (default), `regex`, and `all_branches`
enum:
- wildcard
- regex
- all_branches
vulnerability_events:
type: boolean
description: Trigger hook on vulnerability events
url_variables:
type: array
description: URL variables for interpolation
items:
type: object
properties:
key:
type: string
description: Name of the variable
example: token
value:
type: string
description: Value of the variable
example: '123'
required:
- key
- value
custom_headers:
type: array
description: Custom headers
items:
type: object
properties:
key:
type: string
desc
# --- truncated at 32 KB (38 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/gitlab-ci/refs/heads/main/openapi/gitlab-ci-hooks-api-openapi.yml