Bitbucket Post Webhook sends data to external systems like Jenkins, Azure DevOps and other systems that should be triggered from outside. Repository level configuration guide.

Basic information

Bitbucket Post Webhooks makes it possible to post JSON data to an HTTP/HTTPS address. The data is sent when a configured event occurs and all filters are passed.

Jenkins 2.0 plugin is supported. Azure DevOps Pipelines (Server and Cloud) triggering is supported as well.

More information on how to set up Jenkins.

Main features

  • You can send JSON payload from Bitbucket Server or Data Center to an external system like Jenkins, customer scripts, Serverless functions, etc.

  • Support of Azure DevOps Pipelines (Cloud and Server). You can trigger a pipeline.

  • Microsoft Teams notifications. Just use the Incoming Webhook URL.

  • You can configure the rules on a global, project and repository level. Corresponding permissions are respected.

  • You can configure the HTTP method: POST (default), PUT and GET(not HTTP body sent).

  • Support of Basic, Bearer and Kerberos authentication.

  • Support of Mutual TLS.

  • Support of multiple configurations per level (project or repository) or only 1 configuration per layer. This can be changed in the Global Settings of the App.

  • You can filter events by:

    • Event (including Repository Mirror Synchronised, Build Status Update and other events)

    • Committers

    • Repository masks (on the project and global levels). You can filter down the events handled.

    • Branch masks

      • Branches to ignore (a list of masks)

      • Branches to consider (a list of masks)

      • Possibility to filter by from/to branches (valid for pull request-related events)

      • For instance, if you want to notify/trigger only for the master and develop branch you could use .*master|.develop/. as a branch mask.

    • Project

  • You can use API to create rules. The same APIs are used by the Bitbucket Branch Source Jenkins plugin.

  • Query string parameters support

  • You can skip SSL, URL validations.

  • You can skip notifications for personal projects and repositories.

  • If something is missing please reach out.

Frequently Asked Questions

You can find Bitbucket Post Webhook Frequently Asked Questions here.


Repository configuration

Important: repository configuration by default overrides project and global configuration (this is configurable by the Bitbucket administrators).

To set up webhook posts, you need to select the events and filters about which you want to notify your system. It can be the Jenkins branch source plugin or any other system.

The configuration is available at Repository → Settings → Post Webhooks.

When you start with an empty list you need to add a new configuration.

You need to click “Add webhook“. Here is a picture of how it looks.

Here you need to setup:

  • the title - what is the name of the configuration (can be something random, or meaningful with your repo or person name). Our advice is to name something meaningful to you and your team so that it can be understood later easier.

  • Override project and global settings. It is On by default. You can use this setting to override project and global setup. If it is off, the project and global level configuration will take precedence.

  • the URL - where the data should be sent to. F.e.

    • You can skip SSL verification and test connection with additional auxiliary settings.

    • {project.key} variable can be used as part of the URL to be replaced by the Bitbucket project’s key.

    • {repository.slug} variable can be used as part of the URL to be replaced by the Bitbucket repository’s slug.

    • You can change the HTTP method to be used. Note: getting the HTTP body is NOT sent.

  • You can configure basic authentication and Azure DevOps Pipelines token.

  • Committers to ignore (full match) - the comma-separated list of Bitbucket user names that should not trigger an event. Important: not display names, but usernames. This is often used to ignore pushes from your continuous integration user. For instance, you could put there jenkins-user.

  • From branches to consider (regex) - the comma-separated list of Bitbucket branch regular expressions that should be considered when filtering events. For instance, release/*, tag/*, etc.

  • Destination branches to consider - the comma-separated list of Bitbucket branch regular expressions that should be considered when filtering events for pull requests only. For instance, release/*, tag/*, etc.

  • From branches to ignore (regex) - the comma-separated list of Bitbucket branch regexes that should be ignored. For instance, release/*, tag/*, etc.

  • Destination branches to ignore (regex) - the comma-separated list of Bitbucket branch regexes that should be ignored. For instance, release/*, tag/*, etc.

  • Active - should be On if this configuration is to be used.

  • Select the list of the events that you want to notify your external system about.

  • Skip CI - a setting that allows skipping notification for the pull requests if [ci skip] or [skip ci] is present in the pull request’s title or description.

  • Skip personal - allows skipping of the events from personal projects and repositories. Skips forks.

For instance, you don’t want to notify Jenkins about the changes made by the Jenkins user to not trigger cyclomatic build dependency, so you will add the Jenkins user to the committers to ignore.

Enable multiple rules on the repository level and other settings

Contact your Bitbucket administrator to enable this.

Query string parameters support

The following query string parameters are supported:

  • repository.slug - the repository slug

  • project.key - the project key

  • - the branch name

  • pullrequest.frombranch - the from branch name of the pull request

  • pullrequest.tobranch - the to branch name of the pull request

  • pullrequest.url - the pull request URL

Build status event handling

Bitbucket build status API provides the only commitId and Bitbucket Post Webhooks needs to find rules to process an event. Because App cannot get repository information it uses two approaches to find the repository by commit id:

  • Default (since 3.12.23): we cache commit id and repository id so that we can find repository id by commit id in O(1) time.

  • Repository search (default before 3.12.23): App scans all repositories, and projects, globally where rules exist with Build status notification enabled. This approach is not very performant when a huge repository because it results in a repository scan. This approach is disabled by default since version 3.12.23. You can enable it in the global setting (“Enable repositories scan to find commit for build status“ checkbox).

Trigger Azure DevOps Pipelines Cloud and Server (On-Premises)

You can use Bitbucket Post Webhook App to trigger Azure DevOps Pipelines.

You need to generate an API token that allows executing the required action.

It should allow triggering the build pipelines, nothing more. No code access is required. Only Read and Execute pipelines.

Please set the URL in the provided field.

Azure DevOps Pipeline trigger by Post Webhooks for Bitbucket

And specify the URL to the pipeline in the following format:

The build triggers the source branch. For instance, if you create a branch feature/DEV-123-azure-DevOps-confluence-fix the branch ref will be passed to the pipelines that should check out/clone the right branch.

Cloud: The url should match the following pattern{ORG_NAME}/{PROJECT_NAME}/_build?definitionId={PIPELINE_ID}

Server: The url should match the following pattern https://yoursever/{COLLECTION}/{PROJECT_NAME}/_build?definitionId={DEFINITION_ID}

Azure DevOps Pipelines parameters

Additional details are here.

The following parameters are passed from Bitbucket to Azure DevOps Pipelines:

  • projectKey

  • projectName

  • branch (the branch name)

  • repositorySlug (the repository URL friendly name)

  • repositoryName

  • commit (optional commit hash)

  • commitMessage (optional commit message)

  • sourceBranch

  • destinationBranch

  • userDisplayName

  • userSlug

  • eventType

  • pullRequestId

  • pullRequestTitle

  • pullRequestDescription

  • pullRequestState

Dealing with removed/moved repositories

From version 3.12, App updates or deactivates configurations when a repository or a project is renamed or moved. Which highlights the rules which may need a fix.

Not valid configurations are marked in yellow and shown only at the global level so that the global admin can amend or delete them.

In the older versions, you may see RepositoryMovedException. Follow the document below to delete/change older issues. However, the best approach is to update to the latest version and fix the highlighted rule in the Global configuration.

Kerberos support

KERBEROS is a experimental API. Be sure Bitbucket was started with proper configuration e.g.: JAVA_OPTS=""

Afterwards, you can specify username and password in the authentication section of the configuration screen.

Microsoft Teams support

Incoming webhook generation

Generate an incoming webhook URL for the channel where you want to receive notifications.

Go to the Microsoft Teams channel configuration and add a connector.

microsoft teams Jira connector add connector

Find Incoming Webhook and add one. Put the name as Jira and set the Jira logo.

Set the name and the icon of the Connector.

Copy the webhook URL that will be used later on during the configuration process.


On any level (repository, project or global) you can paste a newly generated URL. No checkboxes are necessary. The App supports the old and new formats of Incoming Webhook URLs.

Rerun the data migration

There is a danger zone in the global settings, where you can delete all existing configurations and rerun migration from older (free versions). We do recommend backup the data first (just in case).


Please navigate to the API documentation - Atlassian Bitbucket Post Webhook API.

Outgoing API contracts are here -

Providing feedback

Please contact us via the Service Desk.


Contact your Bitbucket administrators first. You need to enable debug mode for Bitbucket and supply us with the support zip or Bitbucket log file.