GitLab Project Webhooks API

openapi: 3.0.1
info:
  title: GitLab api/v4/ Admin Project Webhooks API
  version: v4
  description: Needs description.
  termsOfService: https://about.gitlab.com/terms/
  license:
    name: CC BY-SA 4.0
    url: https://gitlab.com/gitlab-org/gitlab/-/blob/master/LICENSE
servers:
- url: https://www.gitlab.com/api/
security:
- ApiKeyAuth: []
tags:
- name: Project Webhooks
  description: Manage webhooks for a specific project.
paths:
  /projects/{id}/hooks:
    get:
      operationId: listProjectWebhooks
      summary: GitLab List Project Webhooks
      description: Returns a list of all webhooks configured for the specified project. Each webhook entry includes its URL, enabled event triggers, and SSL verification settings.
      tags:
      - Project Webhooks
      parameters:
      - $ref: '#/components/parameters/projectId'
      responses:
        '200':
          description: List of project webhooks returned successfully.
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/Webhook'
        '401':
          description: Authentication required.
        '404':
          description: Project not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: addProjectWebhook
      summary: GitLab Add a Webhook to a Project
      description: Creates a new webhook for the specified project. The webhook will receive HTTP POST requests for the configured event triggers. A secret token can be specified for payload verification.
      tags:
      - Project Webhooks
      parameters:
      - $ref: '#/components/parameters/projectId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '201':
          description: Webhook created successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid parameters.
        '401':
          description: Authentication required.
        '404':
          description: Project not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /projects/{id}/hooks/{hook_id}:
    get:
      operationId: getProjectWebhook
      summary: GitLab Get a Project Webhook
      description: Returns configuration details for a specific webhook in a project, including the URL, enabled triggers, and SSL verification setting.
      tags:
      - Project Webhooks
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/hookId'
      responses:
        '200':
          description: Webhook configuration returned successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '401':
          description: Authentication required.
        '404':
          description: Project or webhook not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    put:
      operationId: updateProjectWebhook
      summary: GitLab Update a Project Webhook
      description: Modifies the configuration of an existing project webhook. You can update the URL, secret token, SSL verification setting, and which events trigger the webhook.
      tags:
      - Project Webhooks
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/hookId'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/WebhookInput'
      responses:
        '200':
          description: Webhook updated successfully.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Webhook'
        '400':
          description: Invalid parameters.
        '401':
          description: Authentication required.
        '404':
          description: Project or webhook not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    delete:
      operationId: deleteProjectWebhook
      summary: GitLab Delete a Project Webhook
      description: Removes a webhook from the specified project. Deleted webhooks will no longer receive event deliveries.
      tags:
      - Project Webhooks
      parameters:
      - $ref: '#/components/parameters/projectId'
      - $ref: '#/components/parameters/hookId'
      responses:
        '204':
          description: Webhook deleted successfully.
        '401':
          description: Authentication required.
        '404':
          description: Project or webhook not found.
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    Webhook:
      type: object
      properties:
        id:
          type: integer
          description: The unique identifier of the webhook.
          example: 42
        url:
          type: string
          format: uri
          description: The URL that receives webhook POST requests.
          example: https://gitlab.com/example
        name:
          type: string
          description: Optional name for the webhook.
          example: Example Project
        description:
          type: string
          description: Optional description of the webhook.
          example: Example description
        project_id:
          type: integer
          description: The ID of the project the webhook belongs to.
          example: 42
        created_at:
          type: string
          format: date-time
          description: The date and time the webhook was created.
          example: '2026-04-17T12:00:00Z'
        push_events:
          type: boolean
          description: Whether the webhook triggers on push events.
          example: true
        tag_push_events:
          type: boolean
          description: Whether the webhook triggers on tag push events.
          example: true
        issues_events:
          type: boolean
          description: Whether the webhook triggers on issue events.
          example: true
        confidential_issues_events:
          type: boolean
          description: Whether the webhook triggers on confidential issue events.
          example: true
        merge_requests_events:
          type: boolean
          description: Whether the webhook triggers on merge request events.
          example: true
        note_events:
          type: boolean
          description: Whether the webhook triggers on comment events.
          example: true
        confidential_note_events:
          type: boolean
          description: Whether the webhook triggers on confidential comment events.
          example: true
        job_events:
          type: boolean
          description: Whether the webhook triggers on job status change events.
          example: true
        pipeline_events:
          type: boolean
          description: Whether the webhook triggers on pipeline status change events.
          example: true
        wiki_page_events:
          type: boolean
          description: Whether the webhook triggers on wiki page events.
          example: true
        deployment_events:
          type: boolean
          description: Whether the webhook triggers on deployment events.
          example: true
        releases_events:
          type: boolean
          description: Whether the webhook triggers on release events.
          example: true
        member_events:
          type: boolean
          description: Whether the webhook triggers on group member events.
          example: true
        enable_ssl_verification:
          type: boolean
          description: Whether SSL certificate verification is enabled for the webhook URL.
          example: true
        push_events_branch_filter:
          type: string
          description: Branch name or wildcard pattern to filter push events.
          example: main
        branch_filter_strategy:
          type: string
          enum:
          - wildcard
          - regex
          - all_branches
          description: The strategy used for filtering branches.
          example: wildcard
        alert_status:
          type: string
          description: The current alert status of the webhook based on delivery failures.
          example: '2026-04-17T12:00:00Z'
        disabled_until:
          type: string
          format: date-time
          description: If set, the webhook is temporarily disabled until this time.
          example: example_value
    WebhookInput:
      type: object
      required:
      - url
      properties:
        url:
          type: string
          format: uri
          description: The URL to send webhook POST requests to.
          example: https://gitlab.com/example
        name:
          type: string
          description: Optional name for the webhook.
          example: Example Project
        description:
          type: string
          description: Optional description of the webhook.
          example: Example description
        secret_token:
          type: string
          description: A secret token to validate received payloads. Sent as the X-Gitlab-Token header.
          example: glpat-example-token
        enable_ssl_verification:
          type: boolean
          description: Whether to verify SSL certificates on the webhook URL.
          example: true
        push_events:
          type: boolean
          description: Trigger on push events.
          example: true
        tag_push_events:
          type: boolean
          description: Trigger on tag push events.
          example: true
        issues_events:
          type: boolean
          description: Trigger on issue events.
          example: true
        confidential_issues_events:
          type: boolean
          description: Trigger on confidential issue events.
          example: true
        merge_requests_events:
          type: boolean
          description: Trigger on merge request events.
          example: true
        note_events:
          type: boolean
          description: Trigger on comment events.
          example: true
        confidential_note_events:
          type: boolean
          description: Trigger on confidential comment events.
          example: true
        job_events:
          type: boolean
          description: Trigger on job status change events.
          example: true
        pipeline_events:
          type: boolean
          description: Trigger on pipeline status change events.
          example: true
        wiki_page_events:
          type: boolean
          description: Trigger on wiki page events.
          example: true
        deployment_events:
          type: boolean
          description: Trigger on deployment events.
          example: true
        releases_events:
          type: boolean
          description: Trigger on release events.
          example: true
        member_events:
          type: boolean
          description: Trigger on group member events.
          example: true
        push_events_branch_filter:
          type: string
          description: Branch name or wildcard pattern to filter push events.
          example: main
  parameters:
    hookId:
      name: hook_id
      in: path
      required: true
      description: The ID of the webhook.
      schema:
        type: integer
    projectId:
      name: id
      in: path
      required: true
      description: The ID or URL-encoded path of the project. For example, 42 or namespace%2Fproject-name.
      schema:
        type: string