Atlassian Repositories - Webhooks API

openapi: 3.2.0
info:
  title: Atlassian Bitbucket Repositories - 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: Repositories - Webhooks
paths:
  /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:
      - Repositories - Webhooks
      description: Returns a paginated list of webhooks installed on this repository.
      summary: Atlassian 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: []
      operationId: atlassianListWebhooksForARepository
    post:
      tags:
      - Repositories - Webhooks
      description: 'Creates a new webhook on the specified repository.


        Example:


        ```

        $ curl -X POST -u credentials -H ''Content-Type: application/json''

        https://api.bitbucket.org/2.0/repositories/my-workspace/my-repo-slug/hooks

        -d ''

        {

        "description": "Webhook Description",

        "url": "https://example.com/",

        "active": true,

        "secret": "this is a really bad secret",

        "events": [

        "repo:push",

        "issue:created",

        "issue:updated"

        ]

        }''

        ```


        When the `secret` is provided it will be used as the key to generate a HMAC

        digest value sent in the `X-Hub-Signature` header at delivery time. Passing

        a `null` or empty `secret` or not passing a `secret` will leave the webhook''s

        secret unset. Bitbucket only generates the `X-Hub-Signature` when the webhook''s

        secret is set.


        Note that this call requires the webhook scope, as well as any scope

        that applies to the events that the webhook subscribes to. In the

        example above that means: `webhook`, `repository` and `issue`.


        Also note that the `url` must properly resolve and cannot be an

        internal, non-routed address.'
      summary: Atlassian 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: []
      operationId: atlassianCreateAWebhookForARepository
  /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:
      - Repositories - Webhooks
      description: 'Deletes the specified webhook subscription from the given

        repository.'
      summary: Atlassian 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: []
      operationId: atlassianDeleteAWebhookForARepository
    get:
      tags:
      - Repositories - Webhooks
      description: 'Returns the webhook with the specified id installed on the specified

        repository.'
      summary: Atlassian 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: []
      operationId: atlassianGetAWebhookForARepository
    put:
      tags:
      - Repositories - 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: Atlassian 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: []
      operationId: atlassianUpdateAWebhookForARepository
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
    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
    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
    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:
              - pullrequest:comment_reopened
              - pullrequest:approved
              - issue:comment_created
              - repo:push
              - pullrequest:comment_deleted
              - pullrequest:fulfilled
              - pullrequest:comment_created
              - pullrequest:comment_updated
              - pullrequest:updated
              - repo:commit_status_created
              - pullrequest:unapproved
              - repo:updated
              - pullrequest:comment_resolved
              - repo:transfer
              - repo:commit_status_updated
              - pullrequest:changes_request_created
              - issue:updated
              - repo:created
              - pullrequest:changes_request_removed
              - pullrequest:rejected
              - pullrequest:created
              - issue:created
              - repo:imported
              - repo:commit_comment_created
              - project:updated
              - repo:fork
              - repo:deleted
            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
  securitySchemes:
    basic:
      type: http
      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.
      scheme: basic
    oauth2:
      type: oauth2
      description: OAuth 2 as per [RFC-6749](https://tools.ietf.org/html/rfc6749).
      flows:
        authorizationCode:
          authorizationUrl: https://bitbucket.org/site/oauth2/authorize
          tokenUrl: https://bitbucket.org/site/oauth2/access_token
          scopes:
            email: Read your account's primary email address
            account: Read your account information
            account:write: Read and modify your account information
            team: Read your team membership information
            team:write: Read and modify your team membership information
            repository: Read your repositories
            repository:write: Read and modify your repositories
            repository:admin: Administer your repositories
            repository:delete: Delete your repositories
            project: Read your workspace's project settings and read repositories contained within your workspace's projects
            project:admin: Read and modify settings for projects in your workspace
            pipeline: Access your repositories' build pipelines
            pipeline:write: Access and rerun your repositories' build pipelines
            pipeline:variable: Access your repositories' build pipelines and configure their variables
            runner: Access your workspaces/repositories' runners
            runner:write: Access and edit your workspaces/repositories' runners
            pullrequest: Read your repositories and their pull requests
            pullrequest:write: Read and modify your repositories and their pull requests
            webhook: Read and modify your repositories' webhooks
            issue: Read your repositories' issues
            issue:write: Read and modify your repositories' issues
            snippet: Read your snippets
            snippet:write: Read and modify your snippets
            wiki: Read and modify your repositories' wikis
    api_key:
      name: Authorization
      type: apiKey
      description: API Keys can be used as Basic HTTP Authentication credentials and provide a substitute for the account's actual username and password. API Keys are only available to team accounts and there is only 1 key per account. API Keys do not support scopes and have therefore access to all contents of the account.
      in: header
x-revision: 3c039d08312e
x-atlassian-narrative:
  documents:


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