Skip to main content
Skip table of contents

Atlassian Bitbucket Post Webhook API

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

Version 2

Available since 4.11.25.

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

CODE
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

CODE
[
    {
        "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)

CODE
{
    "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

Available before 4.11.25.

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:

      CODE
      [
          {
              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
          }
      ]
  • Error Response:

    • Code: 404 NOT FOUND
      Content:

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

      OR

    • Code: 401 UNAUTHORIZED
      Content:

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

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

Create post webhook

  • URL

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

  • Method:

    POST

  • Data Params

    JS
    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.'
        }
    }
  • Success Response:

    • Code: 201
      Content:

      JS
      {
          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
      }
  • Error Response:

    • Code: 401 UNAUTHORIZED
      Content:

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

    OR

    • Code: 400 BAD REQUEST
      Content:

      CODE
      {
          "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\"])"
              }
          ]
      }
  • Sample Call:

    CODE
    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
    
  • 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

    CODE
    The same is create. Please check above
  • Success Response:

    • Code: 200
      Content:

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

    • Code: 401 UNAUTHORIZED
      Content:

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

    OR

    • Code: 400 BAD REQUEST
      Content:

      CODE
      {
          "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\"])"
              }
          ]
      }
  • Sample Call:

    CODE
    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
    
  • 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:

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

    OR

    • Code: 404 NOT FOUND
      Content:

      CODE
      Webhook not found
      
  • Sample Call:

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

Examples

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

CODE
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:

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.