Write brokers/services for Bitbucket Cloud

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 Cloud  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 Cloud

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



Was this helpful?

Thanks for your feedback!

Why was this unhelpful?

Have a question about this article?

See questions about this article

Powered by Confluence and Scroll Viewport