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_ 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_ 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_ 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 description: Edit project hook putApiV4HooksHookId: 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 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_ 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 description: Edit system hook putApiV4HooksHookIdCustomHeadersKey: type: object properties: value: type: string description: The value of the custom header required: - value description: Set a custom header putApiV4ProjectsIdHooksHookIdUrlVariablesKey: type: object properties: value: type: string description: The value of the variable required: - value description: Set a url variable API_Entities_ProjectHook: 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 project_id: type: integer format: int32 example: 1 issues_events: type: boolean confidential_issues_events: type: boolean note_events: type: boolean confidential_note_events: type: boolean pipeline_events: type: boolean wiki_page_events: type: boolean deployment_events: type: boolean feature_flag_events: type: boolean job_events: type: boolean releases_events: type: boolean milestone_events: type: boolean emoji_events: type: boolean resource_access_token_events: type: boolean resource_deploy_token_events: type: boolean vulnerability_events: type: boolean 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 - project_id - issues_events - confidential_issues_events - note_events - confidential_note_events - pipeline_events - wiki_page_events - deployment_events - feature_flag_events - job_events - releases_events - milestone_events - emoji_events - resource_access_token_events - resource_deploy_token_events - vulnerability_events description: API_Entities_ProjectHook model putApiV4ProjectsIdHooksHookIdCustomHeadersKey: type: object properties: value: type: string description: The value of the custom header required: - value description: Set a custom header securityDefinitions: access_token_header: type: apiKey name: PRIVATE-TOKEN in: header access_token_query: type: apiKey name: private_token in: query