Manage webhooks

In order to improve user privacy in accordance with GDPR regulations, Bitbucket and other Atlassian Cloud products are updating our product APIs to consolidate how we manage access to personal data. These API changes are necessary to support upcoming improvements to Atlassian products that give users greater control over who can see and access their data.

The short summary is that username endpoints and username fields will stop being available on April 12, 2019, and we’re introducing some new data points that are available immediately to replace them. For more information, visit the API deprecation notice.

Webhooks provide a way to configure Bitbucket Cloud to make requests to your server (or another external service) whenever certain events occur in Bitbucket Cloud. A webhook consists of:

A subject – the resource that generates the events. Currently, this resource is the repository where you create the webhook.
One or more events – the default event is a repository push, but you can select multiple events that can trigger the webhook.
A URL – the endpoint where you want Bitbucket to send the event payloads when a matching event happens.

There are two parts to getting a webhook to work: creating the webhook and triggering the webhook. After you create a webhook for an event, every time that event occurs, Bitbucket sends a payload request that describes the event to the specified URL. Thus, you can think of webhooks as a kind of notification system.

If you're having problems with a webhook, see Troubleshoot Webhooks.

When to use webhooks

Use webhooks to integrate applications with Bitbucket Cloud, for example:

Every time a user pushes commits in a repository, you may want to notify your CI server to start a build.
Every time a user pushes commits or creates a pull request, you may want to display a notification in your application.

Advantages of webhooks

Without webhooks, if you want to detect when events occur in Bitbucket Cloud, you need to poll the API. However, polling the API is inconvenient, inefficient, and error-prone. Consider how SMS messages work on mobile phones. You don't have to check your messages every 5 minutes to see if you have a text because your phone sends you a notification. In the same way, webhooks work like the notification so that the API does not have to check for the same activity every minute.

Create webhooks

You can create a webhook through Bitbucket Cloud or with the API. Use the following steps to create a webhook on a repository in Bitbucket. The administrators of a repository are the only users who can create a webhook on that repository.

You can create up to 50 webhooks per repository.

From Bitbucket, open the repository where you want to add the webhook.
Click Repository settings on the left sidebar.
On the Settings page, select Webhooks on the left sidebar.
Click the Add webhook button to create a webhook for the repository.
On the Add new webhook page, enter a Title with a short description.
Enter the URL to the application or server.
(Optional) If you don't want the webhook to be active after you save, remove the checkmark from Active.
(Optional) If you're using a self-signed certificate and want to disable certificate verification, select Skip certificate verification.
Note: We recommend that you don't disable certificate verification because self-signed certificates are inherently not secure. Read the next section for more information about why you would or wouldn't use self-signed certificates.
If necessary, update the Triggers field.
By default, the trigger for the webhook is a repository push, as demonstrated by the Repository push field. If you want additional or different actions to trigger the webhook, click Choose from a full list of triggers. You will see a list of all the event types that can trigger the webhook.
After you entered all the necessary information for your webhook, click Save.

To create a webhook using the API, you need to know the format of the HTTP request that Bitbucket expects and the format of the HTTP response that Bitbucket returns to your server. Refer to the reference documentation for descriptions and examples of these requests and responses.

You may also need to know the Bitbucket Cloud IP addresses to allowlist.

If you use self-signed certificates

When you create a webhook, Bitbucket provides the Skip certificate verification option, which allows you to disable certificate verification when sending event payload requests to the webhook URL. You may want to use this option if you receive webhooks at an HTTPS endpoint that's using a self-signed SSL certificate. However, because self-signed certificates are inherently not secure, we strongly advise that you don't disable certificate verification unless:

You can't install a valid SSL certificate that a public certificate authority has signed, AND
You're not concerned about the security of your webhooks.

With HTTPS endpoints, the data we deliver is encrypted with a symmetric key which is itself encrypted using the public key of the SSL certificate. However, when using self-signed certificates, the certificate itself cannot be considered trustworthy since it has not been signed by a trusted authority. As a result, when we deliver data via an HTTPS endpoint with a self-signed certificate, we have no way to know that we're communicating with the intended server. That means that without certificate verification, a malicious party can successfully execute a man-in-the-middle (MITM) attack by posing as your server.

If possible, we recommend that you don't disable certificate verification. Obtaining an SSL certificate from a trusted certificate authority is the only way to be confident during the initial key exchange that both parties are who they say they are. That way, you know that the data Bitbucket sends you is encrypted properly with the public key from your certificate, and not someone else's. For some affordable options for SSL certificates, see:

Let's Encrypt, which offers free SSL certificates
Instant SSL by Comodo, which includes a free 90-day trial

Secure webhooks

Bitbucket webhooks work by sending an HTTP POST request to the customer service at a particular URL. It's important that you protect your service from potential attacks. As a workaround, you could allowlist the Bitbucket IPs to restrict who can access your webhook resource. Check out the list of Bitbucket IPs.

Trigger webhooks

When an event associated with a webhook occurs, Bitbucket Cloud sends a request to the webhook URL containing the event payload.

If you want your server to check that the payloads it receives are from Bitbucket, you may need to allowlist certain IP addresses. For more specific information, see What are the Bitbucket Cloud IP addresses I should use to configure my corporate firewall?

You can create webhooks for the following events:

Refer to the event documentation for descriptions and examples of each event payload.

Was this helpful?

It wasn't accurate

It wasn't clear

It wasn't relevant

Bitbucket Support