Atlassian Bitbucket Post Webhook API

This document contains API description for Post Webhooks for Bitbucket, the main documentation is here.

Version 2

REST API base URL: http://localhost:7990/bitbucket/rest/webhook/2.0/configurations

Configuration level

Configuration level depends on "projectKey" and "repositorySlug" properties.
1. Global level - properties are not set.
2. Project key - "projectKey" is set, "repositorySlug" is not set
3. Repository level - both properties are set

Possible event types

TAG_CREATED,
BRANCH_DELETED,
BRANCH_CREATED,
ABSTRACT_REPOSITORY_REFS_CHANGED, -- push event
PULL_REQUEST_DECLINED,
PULL_REQUEST_RESCOPED,
PULL_REQUEST_MERGED,
PULL_REQUEST_REOPENED,
PULL_REQUEST_UPDATED,
PULL_REQUEST_OPENED,
PULL_REQUEST_COMMENT,
PULL_REQUEST_CANCELABLE_COMMENT,
PULL_REQUEST_COMMENT_ACTIVITY,
PULL_REQUEST_DELETED,
BUILD_STATUS_SET,
REPOSITORY_MIRROR_SYNCHRONIZED

It can be gotten from http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/event-types

Full payload

[
    {
        "id": 1,
        "enabled": true,
        "name": "test",
        "destinations": [
            {
                "url": "http://localhost:8080/test"
            }
        ]
        "ignoredSources": [],
        "users": [],
        "ignoredUsers": [],
        "groups": [],
        "ignoredGroups": [],
        "projectKey": "PROJECT_1",
        "repositorySlug": "rep_1",
        "eventTypes": [
            "TAG_CREATED",
            "BRANCH_DELETED",
            "BRANCH_CREATED",
            "ABSTRACT_REPOSITORY_REFS_CHANGED",
            "PULL_REQUEST_DECLINED",
            "PULL_REQUEST_RESCOPED",
            "PULL_REQUEST_MERGED",
            "PULL_REQUEST_REOPENED",
            "PULL_REQUEST_UPDATED",
            "PULL_REQUEST_OPENED",
            "PULL_REQUEST_COMMENT",
            "PULL_REQUEST_CANCELABLE_COMMENT",
            "PULL_REQUEST_COMMENT_ACTIVITY",
            "PULL_REQUEST_DELETED",
            "BUILD_STATUS_SET",
            "REPOSITORY_MIRROR_SYNCHRONIZED"
        ],
        "pullRequestBranchSource": "FROM",
        "ignoreCerts": false,
        "ignoreURLValidation": false,
        "override": true,
        "skipCI": true,
        "azureDevOps": false,
        "skipPersonalProjects": false,
        "azureDevOpsToken": "xxxxxx",
        "azureSource": "CLOUD",
        "azureSourceBranch": "",
        "azureParameters": [],
        "httpMethod": "POST",
        "enableAuthentication": false,
        "authenticationType": "BASIC",
        "authUsername": "",
        "authPassword": "xxxxxx",
        "mutualAuthenticationEnabled": false,
        "trustStorePassword": "",
        "keyStorePassword": "",
        "trustStore": "",
        "keyStore": "",
        "repositoryPattern": "",
        "filePathPatterns": []
    }
]

Smallest payload

The smallest payload which can be used(corresponding to the version 1 API)

{
    "enabled": true,
    "name": "test",
    "destinations": [
        {
            "url": "http://localhost:8080/test"
        }
    ],
    "projectKey": "PROJECT_1",
    "repositorySlug": "rep_1",
    "eventTypes": [
        "TAG_CREATED",
        "BRANCH_DELETED",
        "BRANCH_CREATED",
        "ABSTRACT_REPOSITORY_REFS_CHANGED"
    ]
}

Get configurations

GET http://localhost:7990/bitbucket/rest/webhook/2.0/configurations?projectKey=PROJECT&repositorySlug=REPOSITORY

• projectKey, repositorySlug - optional parameters

Create configuration

POST http://localhost:7990/bitbucket/rest/webhook/2.0/configurations payload

Update configuration

PUT http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/ID payload

Delete configuration

DELETE http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/ID

Disable batch of configurations

PUT http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/disable?bulkIds=ID1,ID2,ID3

Enable batch of configurations

PUT http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/enable?bulkIds=ID1,ID2,ID3

Delete a batch of configurations

DELETE http://localhost:7990/bitbucket/rest/webhook/2.0/configurations/delete?bulkIds=ID1,ID2,ID3

Version 1

Get existing post webhooks for a specified project

• URL

/rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations

• Method

GET

Response

• Success Response:

  • Code: 200
    Content:

    [
        {
            id: 21,
            title: "Jenkins hook",
            url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify",
            committersToIgnore: "jdoe",
            branchesToIgnore: "release/*",
            enabled: true,
            skipCI: true,
            tagCreated: true,
            branchDeleted: true,
            branchCreated: true,
            repoPush: true,
            prDeclined: true,
            prRescoped: true,
            prMerged: true,
            prReopened: true,
            prUpdated: true,
            prCreated: true,
            prCommented: true,
            prDeleted: true,
            buildStatus: true,
            repoMirrorSynced: true
        },
        {
            id: 642,
            title: "Other Site hook",
            url: "http://local-site.com/path/to/hook",
            skipCI: falsem
            enabled: true
        }
    ]

    CODE

• Error Response:

  • Code: 404 NOT FOUND
    Content:

    {
        errors: [
            {
                context: null,
                message: "Repository iprepo/eric-test3 does not exist.",
                exceptionName: "com.atlassian.bitbucket.repository.NoSuchRepositoryException"
            }
        ]
    }

    JS

    OR

  • Code: 401 UNAUTHORIZED
    Content:

    {
        "errors": [
            {
                "context": null, 
                "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", 
                "message": "Authentication failed. Please check your credentials and try again."
            }
        ]
    }

    JS

• Sample Call:

  curl -u '$USER:$PASSWORD' -H "Content-Type: application/json" -X GET $BITBUCKET_SERVER_URL/rest/webhook/1

  CODE

Create post webhook

• URL

  /rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations

• Method:

  POST

• Data Params

  schema: {
      'title': {
          'type': 'string', 
          'description': 'The title of the post webhook - used for naming only.'
      },
      'url': {
          'type': 'string',
          'description': 'The url of the webhook.'
      },
      'enabled': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is enabled.'
      },
      'committersToIgnore': {
          'type': 'string',
          'description': "Comma separated list of user ids in bitbucket to ignore commits from for triggering the webhook"
      },
      'branchesToIgnore': {
          'type': 'string',
          'description': "Comma separated list of branch masks to ignore notifications from"
      },
      'skipCI': {
          'type': 'boolean',
          'description': 'Do not post webhooks if the title or description of a PR, or the last commit message contain "[ci skip]" or "[skip ci]".'
      },
      'tagCreated': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on tag created event.'
      },
      'branchDeleted': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on branch deleted event.'
      },
      'branchCreated': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on branch created event.'
      },
      'repoPush': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on repository pushed event.'
      },
      'prDeclined': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request declined event.'
      },
      'prRescoped': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request rescoped event.'
      },
      'prMerged': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request merged event.'
      },
      'prReopened': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request opened event.'
      },
      'prUpdated': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request updated event.'
      },
      'prCreated': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request created event.'
      },
      'prCommented': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on pull request commented event.'
      },
      'prDeleted': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on branch created event.'
      },
      'buildStatus': {
          'type': 'boolean',
          'description': 'Toggle whether or not the webhook is sent on build status channged event.'
      }
  }

  JS

• Success Response:

  • Code: 201
    Content:

    {
        id: 21,
        title: "Jenkins hook",
        url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify",
        committersToIgnore: "jdoe",
        branchesToIgnore: "",
        skipCI: true,
        enabled: true
        // the events are set as below 
    }
    // OR the below request
    {
        id: 21,
        title: "Jenkins hook",
        url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify",
        committersToIgnore: "jdoe",
        branchesToIgnore: "",
        enabled: true,
        skipCI: true,
        
        tagCreated: false,
        branchDeleted: true,
        branchCreated: true,
        repoPush: true,
        prDeclined: true,
        prRescoped: true,
        prMerged: true,
        prReopened: true,
        prUpdated: true,
        prCreated: true,
        prCommented: false,
        prDeleted: false,
        buildStatus: false,
        repoMirrorSynced: false
    }

    JS

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
        "errors": [
            {
                "context": null, 
                "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", 
                "message": "Authentication failed. Please check your credentials and try again."
            }
        ]
    }

    CODE

  OR

  • Code: 400 BAD REQUEST
    Content:

    {
        "errors": [
            {
                "context": "fake_field", 
                "exceptionName": null, 
                "message": "Unrecognized field \"fake_field\" (Class nl.topicus.bitbucket.api.WebHookConfigurationModel), not marked as ignorable\n at [Source: com.atlassian.stash.internal.web.util.web.CountingServletInputStream@527f4356; line: 3, column: 16] (through reference chain: nl.topicus.bitbucket.api.WebHookConfigurationModel[\"titlee\"])"
            }
        ]
    }

    CODE

• Sample Call:

  curl -u user:password -H Content-Type: application/json -X POST -d {title: http://jenkins.example.com, url: http://jenkins.example.com/bitbucket-scmsource-hook/notify, enabled: true} 
  https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations
  

  CODE

• Notes:

  This endpoint, the creation of a post webhook, can also be called as a 'PUT' request to maintain backward compatibility. However, The proper API verb for the creation of a new resource is 'POST'

Update a post webhook by ID

• URL

  /rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID

• Method:

  PUT

• Data Params

  The same is create. Please check above

  CODE

• Success Response:

  • Code: 200
    Content:

    {
        id: 21,
        title: "Jenkins hook",
        url: "http://local-jenkins.com/bitbucket-scmsource-hook/notify",
        committersToIgnore: "jdoe",
        branchesToIgnore: "",
        skipCI: true,
        enabled: true
    }

    CODE

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
        "errors": [
            {
                "context": null, 
                "exceptionName": "com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException", 
                "message": "Authentication failed. Please check your credentials and try again."
            }
        ]
    }

    CODE

  OR

  • Code: 400 BAD REQUEST
    Content:

    {
        "errors": [
            {
                "context": "fake_field", 
                "exceptionName": null, 
                "message": "Unrecognized field \"fake_field\" (Class nl.topicus.bitbucket.api.WebHookConfigurationModel), not marked as ignorable\n at [Source: com.atlassian.stash.internal.web.util.web.CountingServletInputStream@527f4356; line: 3, column: 16] (through reference chain: nl.topicus.bitbucket.api.WebHookConfigurationModel[\"titlee\"])"
            }
        ]
    }

    CODE

• Sample Call:

  curl -u user:password -H Content-Type: application/json -X PUT -d {title: http://jenkins.example.com, url: http://jenkins.example.com/bitbucket-scmsource-hook/notify, enabled: true} 
  https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations
  

  CODE

• Notes:

  This endpoint, the update of an existing post webhook, can also be called as a 'POST' request to maintain backward compatibility. However, The proper API verb for updates to an existing resource is 'PUT'

Delete a post webhook by ID

• URL

  /rest/webhook/1.0/projects/$PROJECT/repos/$REPO/configurations/$WEBHOOK_ID

• Method:

  DELETE

• Success Response:

  • Code: 204
    

• Error Response:

  • Code: 401 UNAUTHORIZED
    Content:

    {
        "errors": [
            {
                "context":null,
                "message":"Authentication failed. Please check your credentials and try again.",
                "exceptionName":"com.atlassian.bitbucket.auth.IncorrectPasswordAuthenticationException"
            }
        ]
    }

    CODE

  OR

  • Code: 404 NOT FOUND
    Content:

    Webhook not found
    

    CODE

• Sample Call:

  curl -u $USER:$PASSWORD -H Content-Type: application/json -X DELETE $BITBUCKET_SERVER_URL/rest/webhook/1.

  CODE

Examples

Create a webhook on the pull request created or re-scoped.

curl -u user:password \
    -H Content-Type: application/json \
    -X POST \
    -d {title: http://jenkins.example.com, url: http://jenkins.example.com/bitbucket-scmsource-hook/notify, enabled: true, skipCI: true, prCreated: true, prRescoped: true } \
https://my.bitbucket.server.com/rest/webhook/1.0/projects/MyProject/repos/MyRepo/configurations

How to disable Old REST APIs?

You can do this in the global settings.

Last updated: 11 Jan 2023