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.

Contact Support Close