Write brokers/services for Bitbucket

Deprecation Notice

In the future, you will no longer be able to create a POST service from the Services screen, as Bitbucket’s updated webhooks will replace this service. Existing services will continue to function as expected for now.

To create a new webhook, refer to the webhooks documentation.

No longer accepting new brokers

We are no longer accepting new brokers. Please refer to the information below about using the POST service.

Bitbucket integrates with external services through a set of brokers that run in response to certain events.  Brokers are Python scripts that receive information about an event and then take one or more actions. For example, there is a Bamboo broker for integrating with Bamboo.   The Bitbucket team developed many of our brokers. Third-party vendors also developed several brokers.

Using the POST service to integrate your application with Bitbucket

Most third-party web applications have a public RESTAPI. For example, Jenkins has a one.  Using a third-party API, you can pass parameters to the service using Bitbucket's POST service.  Bitbucket's POST service passes a payload to your third-party web application through its API.  Your third-party application is responsible for receiving and transforming the payload.

To add a POST service to the Bitbucket repository:

  1. Review the third-party REST API for the appropriate POST call.
    For example, your URL can include a user token such as:
    http://myservice/broker?token=bfkbd
  2. Navigate to your repository  settings.
  3. Choose Services from the left-hand navigation.
    The Services page displays. 
  4. Choose POST from the services dropdown.
  5. Press Add service.
  6. Enter the URL for your third-party service.
  7. Press Save.
    The new POST service appears in the active Services list. 

The next time a user pushes to your repository, the POST service fires and sends a payload of data to your service. The service should receive the payload and handle the data appropriately using our REST API.   For example, the application could call back into Bitbucket for specific resources using OAuth or other information, if needed.

The payload sent to your service by the service

The push payload, is a uniform dictionary containing information on the repository, the commits, and the service-specific values. 

When a user makes a push against a repository, Bitbucket POSTs to the URL you provided. The body of POST request contains information about the repository where the change originated, a list of recent commits, and the user that made the push. 

Example

Mercurial
Git

Was this helpful?

Thanks for your feedback!

8 Archived comments

  1. User avatar

    Anonymous

    Including a version of BaseBroker (or just the source of the get_local method) would make it considerably easier to write a broker.

    05 Mar 2011
    1. User avatar

      Anonymous

      class BaseBroker():
         def get_local(self, arg, theclass):
           return theclass()

      05 Mar 2011
  2. User avatar

    Anonymous

    It would be really helpful if we could see the code of existing brokers to troubleshoot issues or extend their functionality. I would like to extend the Jenkins service to support authenticated builds, for example. 

    30 Mar 2012
  3. User avatar

    Anonymous

    Is is possible to include tags information in the payload?

    04 May 2012
    1. User avatar

      manthony

      Hi,

      We do not include tag information in the broker payload. We only include branch information.  If you would like to file an enhancement request please go to:

      https://bitbucket.org/site/master/issues/new

      Regards,

      M

       

       

      04 May 2012
  4. User avatar

    Trent Clarke

    What events do the brokers fire on? Is it only on a push, or are there others?

    EDIT: We'd like our jenkins instance to respond to pull requests, in order to test them before they hit our mainline code. I'm assuming that we'd need a notification of a pull request to do this, but if there's another way I'm open to it.

    24 Jul 2013
  5. User avatar

    David Harris

    I would really love to see a post notification of a repository added to an account, as well as the ability to manage project specific hooks from an API. 

    18 Dec 2013
  6. User avatar

    Shea Martin

    Is raw_author a reliable way to get the user's email address? There doesn't seem to be a way to do this with the API.

    06 Nov 2014
Powered by Confluence and Scroll Viewport