Skip to main content
Skip table of contents

How to manage configurations using Post Webhooks for Bitbucket APIs?

This guide is for Post Webhooks for the Bitbucket Atlassian Marketplace application.

Managing configurations using the Post Webhooks for Bitbucket APIs allows you to programmatically create, update, retrieve, and delete webhook configurations.

Here's an overview of how to manage configurations using the APIs.

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

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)

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

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 disable Old REST APIs on the Global configuration page:

  1. Move to the Bitbucket Administration section (“gear” button in the right corner of the navigation menu).

  2. Navigate to the Add-ons section and find our application Post Webhooks.

  3. On the Global Configuration page, navigate to the Global Settings tab.

  4. Tick the checkbox Disable Old Rest API and click on the Save button.

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