Bitbucket Webhooks API

openapi: 3.2.0
info:
  title: Bitbucket Addon Webhooks API
  description: Code against the Bitbucket API to automate simple tasks, embed Bitbucket data into your own site, build mobile or desktop apps, or even add custom UI add-ons into Bitbucket itself using the Connect framework.
  version: '2.0'
  termsOfService: https://www.atlassian.com/legal/customer-agreement
  contact:
    name: Bitbucket Support
    url: https://support.atlassian.com/bitbucket-cloud/
    email: support@bitbucket.org
servers:
- url: https://api.bitbucket.org/2.0
tags:
- name: Webhooks
  description: 'Webhooks provide a way to configure Bitbucket Cloud to make requests to

    your server (or another external service) whenever certain events occur in

    Bitbucket Cloud.


    A webhook consists of:


    * A subject -- The resource that generates the events. Currently, this resource

    is the repository, user account, or team where you create the webhook.

    * One or more event -- The default event is a repository push, but you can

    select multiple events that can trigger the webhook.

    * A URL -- The endpoint where you want Bitbucket to send the event payloads

    when a matching event happens.


    There are two parts to getting a webhook to work: creating the webhook and

    triggering the webhook. After you create a webhook for an event, every time

    that event occurs, Bitbucket sends a payload request that describes the event

    to the specified URL. Thus, you can think of webhooks as a kind of

    notification system.


    Use webhooks to integrate applications with Bitbucket Cloud. The following

    use cases provides examples of when you would want to use webhooks:


    * Every time a user pushes commits in a repository, you may want to notify

    your CI server to start a build.

    * Every time a user pushes commits or creates a pull request, you may want to

    display a notification in your application.

    '
paths:
  /hook_events:
    parameters: []
    get:
      tags:
      - Webhooks
      description: 'Returns the webhook resource or subject types on which webhooks can

        be registered.


        Each resource/subject type contains an `events` link that returns the

        paginated list of specific events each individual subject type can

        emit.


        This endpoint is publicly accessible and does not require

        authentication or scopes.'
      summary: Get a webhook resource
      responses:
        '200':
          description: A mapping of resource/subject types pointing to their individual event types.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/subject_types'
              example:
                repository:
                  links:
                    events:
                      href: https://api.bitbucket.org/2.0/hook_events/repository
                workspace:
                  links:
                    events:
                      href: https://api.bitbucket.org/2.0/hook_events/workspace
      security:
      - oauth2: []
      - basic: []
      - api_key: []
  /hook_events/{subject_type}:
    parameters:
    - name: subject_type
      in: path
      description: A resource or subject type.
      required: true
      schema:
        type: string
        enum:
        - repository
        - workspace
    get:
      tags:
      - Webhooks
      description: 'Returns a paginated list of all valid webhook events for the

        specified entity.

        **The team and user webhooks are deprecated, and you should use workspace instead.

        For more information, see [the announcement](https://developer.atlassian.com/cloud/bitbucket/bitbucket-api-teams-deprecation/).**


        This is public data that does not require any scopes or authentication.


        NOTE: The example response is a truncated response object for the `workspace` `subject_type`.

        We return the same structure for the other `subject_type` objects.'
      summary: List subscribable webhook types
      responses:
        '200':
          description: A paginated list of webhook types available to subscribe on.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_hook_events'
              example:
                page: 1
                pagelen: 30
                size: 4
                values:
                - category: Repository
                  description: Whenever a repository push occurs
                  event: repo:push
                  label: Push
                - category: Repository
                  description: Whenever a repository fork occurs
                  event: repo:fork
                  label: Fork
                - category: Repository
                  description: Whenever a repository import occurs
                  event: repo:imported
                  label: Import
                - category: Pull Request
                  label: Approved
                  description: When someone has approved a pull request
                  event: pullrequest:approved
        '404':
          description: If an invalid `{subject_type}` value was specified.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2: []
      - basic: []
      - api_key: []
  /repositories/{workspace}/{repo_slug}/hooks:
    parameters:
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

        surrounded by curly-braces, for example: `{repository UUID}`.

        '
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Webhooks
      description: Returns a paginated list of webhooks installed on this repository.
      summary: List webhooks for a repository
      responses:
        '200':
          description: The paginated list of installed webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_webhook_subscriptions'
        '403':
          description: If the authenticated user does not have permission to access the webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
    post:
      tags:
      - Webhooks
      description: "Creates a new webhook on the specified repository.\n\nExample:\n\n```\n$ curl -X POST -u credentials -H 'Content-Type: application/json'\n  https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo-slug/hooks\n  -d '\n    {\n      \"description\": \"Webhook Description\",\n      \"url\": \"https://example.com/\",\n      \"active\": true,\n      \"secret\": \"this is a really bad secret\",\n      \"events\": [\n        \"repo:push\",\n        \"issue:created\",\n        \"issue:updated\"\n      ]\n    }'\n```\n\nWhen the `secret` is provided it will be used as the key to generate a HMAC\ndigest value sent in the `X-Hub-Signature` header at delivery time. Passing\na `null` or empty `secret` or not passing a `secret` will leave the webhook's\nsecret unset. Bitbucket only generates the `X-Hub-Signature` when the webhook's\nsecret is set.\n\nNote that this call requires the webhook scope, as well as any scope\nthat applies to the events that the webhook subscribes to. In the\nexample above that means: `webhook`, `repository` and `issue`.\n\nAlso note that the `url` must properly resolve and cannot be an\ninternal, non-routed address."
      summary: Create a webhook for a repository
      responses:
        '201':
          description: If the webhook was registered successfully.
          headers:
            Location:
              description: The URL of new newly created webhook.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_subscription'
        '403':
          description: If the authenticated user does not have permission to install webhooks on the specified repository.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
        - write:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
  /repositories/{workspace}/{repo_slug}/hooks/{uid}:
    parameters:
    - name: repo_slug
      in: path
      description: 'This can either be the repository slug or the UUID of the repository,

        surrounded by curly-braces, for example: `{repository UUID}`.

        '
      required: true
      schema:
        type: string
    - name: uid
      in: path
      description: Installed webhook's ID
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    delete:
      tags:
      - Webhooks
      description: 'Deletes the specified webhook subscription from the given

        repository.'
      summary: Delete a webhook for a repository
      responses:
        '204':
          description: When the webhook was deleted successfully
        '403':
          description: If the authenticated user does not have permission to delete the webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the webhook or repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - delete:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
    get:
      tags:
      - Webhooks
      description: 'Returns the webhook with the specified id installed on the specified

        repository.'
      summary: Get a webhook for a repository
      responses:
        '200':
          description: The webhook subscription object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_subscription'
        '404':
          description: If the webhook or repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
    put:
      tags:
      - Webhooks
      description: 'Updates the specified webhook subscription.


        The following properties can be mutated:


        * `description`

        * `url`

        * `secret`

        * `active`

        * `events`


        The hook''s secret is used as a key to generate the HMAC hex digest sent in the

        `X-Hub-Signature` header at delivery time. This signature is only generated

        when the hook has a secret.


        Set the hook''s secret by passing the new value in the `secret` field. Passing a

        `null` value in the `secret` field will remove the secret from the hook. The

        hook''s secret can be left unchanged by not passing the `secret` field in the

        request.'
      summary: Update a webhook for a repository
      responses:
        '200':
          description: The webhook subscription object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_subscription'
        '403':
          description: If the authenticated user does not have permission to update the webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the webhook or repository does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
        - write:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
  /workspaces/{workspace}/hooks:
    parameters:
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    get:
      tags:
      - Webhooks
      description: Returns a paginated list of webhooks installed on this workspace.
      summary: List webhooks for a workspace
      responses:
        '200':
          description: The paginated list of installed webhooks.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/paginated_webhook_subscriptions'
        '403':
          description: If the authenticated user is not an owner on the specified workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the specified workspace does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
    post:
      tags:
      - Webhooks
      description: "Creates a new webhook on the specified workspace.\n\nWorkspace webhooks are fired for events from all repositories contained\nby that workspace.\n\nExample:\n\n```\n$ curl -X POST -u credentials -H 'Content-Type: application/json'\n  https://api.bitbucket.org/2.0/workspaces/my-workspace/hooks\n  -d '\n    {\n      \"description\": \"Webhook Description\",\n      \"url\": \"https://example.com/\",\n      \"active\": true,\n      \"secret\": \"this is a really bad secret\",\n      \"events\": [\n        \"repo:push\",\n        \"issue:created\",\n        \"issue:updated\"\n      ]\n    }'\n```\n\nWhen the `secret` is provided it will be used as the key to generate a HMAC\ndigest value sent in the `X-Hub-Signature` header at delivery time. Passing\na `null` or empty `secret` or not passing a `secret` will leave the webhook's\nsecret unset. Bitbucket only generates the `X-Hub-Signature` when the webhook's\nsecret is set.\n\nThis call requires the webhook scope, as well as any scope\nthat applies to the events that the webhook subscribes to. In the\nexample above that means: `webhook`, `repository` and `issue`.\n\nThe `url` must properly resolve and cannot be an internal, non-routed address.\n\nOnly workspace owners can install webhooks on workspaces."
      summary: Create a webhook for a workspace
      responses:
        '201':
          description: If the webhook was registered successfully.
          headers:
            Location:
              description: The URL of new newly created webhook.
              schema:
                type: string
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_subscription'
        '403':
          description: If the authenticated user does not have permission to install webhooks on the specified workspace.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the specified workspace does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
        - write:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
  /workspaces/{workspace}/hooks/{uid}:
    parameters:
    - name: uid
      in: path
      description: Installed webhook's ID
      required: true
      schema:
        type: string
    - name: workspace
      in: path
      description: 'This can either be the workspace ID (slug) or the workspace UUID

        surrounded by curly-braces, for example: `{workspace UUID}`.

        '
      required: true
      schema:
        type: string
    delete:
      tags:
      - Webhooks
      description: Deletes the specified webhook subscription from the given workspace.
      summary: Delete a webhook for a workspace
      responses:
        '204':
          description: When the webhook was deleted successfully
        '403':
          description: If the authenticated user does not have permission to delete the webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the webhook or workspace does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - delete:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
    get:
      tags:
      - Webhooks
      description: 'Returns the webhook with the specified id installed on the given

        workspace.'
      summary: Get a webhook for a workspace
      responses:
        '200':
          description: The webhook subscription object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_subscription'
        '404':
          description: If the webhook or workspace does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
    put:
      tags:
      - Webhooks
      description: 'Updates the specified webhook subscription.


        The following properties can be mutated:


        * `description`

        * `url`

        * `secret`

        * `active`

        * `events`


        The hook''s secret is used as a key to generate the HMAC hex digest sent in the

        `X-Hub-Signature` header at delivery time. This signature is only generated

        when the hook has a secret.


        Set the hook''s secret by passing the new value in the `secret` field. Passing a

        `null` value in the `secret` field will remove the secret from the hook. The

        hook''s secret can be left unchanged by not passing the `secret` field in the

        request.'
      summary: Update a webhook for a workspace
      responses:
        '200':
          description: The webhook subscription object.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/webhook_subscription'
        '403':
          description: If the authenticated user does not have permission to update the webhook.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
        '404':
          description: If the webhook or workspace does not exist.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/error'
      security:
      - oauth2:
        - webhook
      - basic: []
      - api_key: []
      x-atlassian-oauth2-scopes:
      - state: Current
        scheme: oauth2
        scopes:
        - read:webhook:bitbucket
        - write:webhook:bitbucket
      x-atlassian-auth-types:
      - api-token
components:
  schemas:
    paginated_webhook_subscriptions:
      type: object
      title: Paginated Webhook Subscriptions
      description: A paginated list of webhook subscriptions
      properties:
        size:
          type: integer
          description: Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute.
          minimum: 0
        page:
          type: integer
          description: Page number of the current results. This is an optional element that is not provided in all responses.
          minimum: 1
        pagelen:
          type: integer
          description: Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values.
          minimum: 1
        next:
          type: string
          description: Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs.
          format: uri
        previous:
          type: string
          description: Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs.
          format: uri
        values:
          type: array
          items:
            $ref: '#/components/schemas/webhook_subscription'
          minItems: 0
          uniqueItems: true
      additionalProperties: false
    paginated_hook_events:
      type: object
      title: Paginated Hook Events
      description: A paginated list of webhook types available to subscribe on.
      properties:
        size:
          type: integer
          description: Total number of objects in the response. This is an optional element that is not provided in all responses, as it can be expensive to compute.
          minimum: 0
        page:
          type: integer
          description: Page number of the current results. This is an optional element that is not provided in all responses.
          minimum: 1
        pagelen:
          type: integer
          description: Current number of objects on the existing page. The default value is 10 with 100 being the maximum allowed value. Individual APIs may enforce different values.
          minimum: 1
        next:
          type: string
          description: Link to the next page if it exists. The last page of a collection does not have this value. Use this link to navigate the result set and refrain from constructing your own URLs.
          format: uri
        previous:
          type: string
          description: Link to previous page if it exists. A collections first page does not have this value. This is an optional element that is not provided in all responses. Some result sets strictly support forward navigation and never provide previous links. Clients must anticipate that backwards navigation is not always available. Use this link to navigate the result set and refrain from constructing your own URLs.
          format: uri
        values:
          type: array
          items:
            $ref: '#/components/schemas/hook_event'
          minItems: 0
          uniqueItems: true
      additionalProperties: false
    subject_types:
      type: object
      title: Subject Types
      description: The mapping of resource/subject types pointing to their individual event types.
      properties:
        repository:
          type: object
          properties:
            events:
              type: object
              title: Link
              description: A link to a resource related to this object.
              properties:
                href:
                  type: string
                  format: uri
                name:
                  type: string
              additionalProperties: false
          additionalProperties: false
        workspace:
          type: object
          properties:
            events:
              type: object
              title: Link
              description: A link to a resource related to this object.
              properties:
                href:
                  type: string
                  format: uri
                name:
                  type: string
              additionalProperties: false
          additionalProperties: false
      additionalProperties: false
    error:
      type: object
      title: Error
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
        error:
          type: object
          properties:
            message:
              type: string
            detail:
              type: string
            data:
              type: object
              description: Optional structured data that is endpoint-specific.
              properties: {}
              additionalProperties: true
          required:
          - message
          additionalProperties: false
      required:
      - type
      additionalProperties: true
    object:
      type: object
      description: Base type for most resource objects. It defines the common `type` element that identifies an object's type. It also identifies the element as Swagger's `discriminator`.
      properties:
        type:
          type: string
      required:
      - type
      additionalProperties: true
      discriminator:
        propertyName: type
    webhook_subscription:
      allOf:
      - $ref: '#/components/schemas/object'
      - type: object
        title: Webhook Subscription
        description: A Webhook subscription.
        properties:
          uuid:
            type: string
            description: The webhook's id
          url:
            type: string
            description: The URL events get delivered to.
            format: uri
          description:
            type: string
            description: A user-defined description of the webhook.
          subject_type:
            type: string
            description: The type of entity. Set to either `repository` or `workspace` based on where the subscription is defined.
            enum:
            - repository
            - workspace
          subject:
            $ref: '#/components/schemas/object'
          active:
            type: boolean
          created_at:
            type: string
            format: date-time
          events:
            type: array
            description: The events this webhook is subscribed to.
            items:
              type: string
              enum:
              - issue:comment_created
              - issue:created
              - issue:updated
              - pipeline:span_created
              - project:updated
              - pullrequest:approved
              - pullrequest:changes_request_created
              - pullrequest:changes_request_removed
              - pullrequest:comment_created
              - pullrequest:comment_deleted
              - pullrequest:comment_reopened
              - pullrequest:comment_resolved
              - pullrequest:comment_updated
              - pullrequest:created
              - pullrequest:fulfilled
              - pullrequest:push
              - pullrequest:rejected
              - pullrequest:unapproved
              - pullrequest:updated
              - repo:commit_comment_created
              - repo:commit_status_created
              - repo:commit_status_updated
              - repo:created
              - repo:deleted
              - repo:fork
              - repo:imported
              - repo:push
              - repo:transfer
              - repo:updated
            minItems: 1
            uniqueItems: true
          secret_set:
            type: boolean
            description: Indicates whether or not the hook has an associated secret. It is not possible to see the hook's secret. This field is ignored during updates.
          secret:
            type: string
            description: The secret to associate with the hook. The secret is never returned via the API. As such, this field is only used during updates. The secret can be set to `null` or "" to remove the secret (or create a hook with no secret). Leaving out the secret field during updates will leave the secret unchanged. Leaving out the secret during creation will create a hook with no secret.
            minLength: 0
            maxLength: 128
        additionalProperties: true
    hook_event:
      type: object
      title: Hook Event
      description: An event, associated with a resource or subject type.
      properties:
        event:
          type: string
          description: The event identifier.
          enum:
          - issue:comment_created
          - issue:created
          - issue:updated
          - pipeline:span_created
          - project:updated
          - pullrequest:approved
          - pullrequest:changes_request_created
          - pullrequest:changes_request_removed
          - pullrequest:comment_created
          - pullrequest:comment_deleted
          - pullrequest:comment_reopened
          - pullrequest:comment_resolved
          - pullrequest:comment_updated
          - pullrequest:created
          - pullrequest:fulfilled
          - pullrequest:push
          - pullrequest:rejected
          - pullrequest:unapproved
          - pullrequest:updated
          - repo:commit_comment_created
          - repo:commit_status_created
          - repo:commit_status_updated
          - repo:created
          - repo:deleted
          - repo:fork
          - repo:imported
          - repo:push
          - repo:transfer
          - repo:updated
        category:
          type: string
          description: The category this event belongs to.
        label:
          type: string
          description: Summary of the webhook event type.
        description:
          type: string
          description: More detailed description of the webhook event type.
      additionalProperties: false
  securitySchemes:
    basic:
      type: http
      scheme: basic
      description: Basic HTTP Authentication as per [RFC-2617](https://tools.ietf.org/html/rfc2617) (Digest not supported). Note that Basic Auth is available only with username and app password as credentials.
    oauth2:
      type: oauth2
      flows:
        authorizationCode:
          scopes:
            repository: Read your reposi

# --- truncated at 32 KB (144 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/bitbucket/refs/heads/main/openapi/bitbucket-webhooks-api-openapi.yml