GitLab Project Webhooks API

openapi: 3.2.0
info:
  title: GitLab Webhooks Project Webhooks API
  description: The GitLab Webhooks API provides REST endpoints for managing project and group webhooks. Webhooks can be configured to send HTTP POST requests to external URLs when events occur in GitLab, such as pushes, merge requests, issues, pipelines, and deployments. This API covers webhook configuration, event history, and test trigger operations.
  version: '4'
  contact:
    name: GitLab Support
    url: https://about.gitlab.com/support/
  termsOfService: https://about.gitlab.com/terms/
servers:
- url: https://gitlab.com/api/v4
  description: GitLab.com Production Server
security:
- privateToken: []
- bearerAuth: []
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:
    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
    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
  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
  securitySchemes:
    privateToken:
      type: apiKey
      in: header
      name: PRIVATE-TOKEN
      description: GitLab personal access token or project access token.
    bearerAuth:
      type: http
      scheme: bearer
      description: OAuth 2.0 access token.
externalDocs:
  description: GitLab Project Webhooks API Documentation
  url: https://docs.gitlab.com/api/project_webhooks/