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.
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.
- From Bitbucket, open the repository where you want to add the webhook.
- Click the Settings link on the left side.
- From the links on the Settings page, click the Webhooks link.
- Click the Add webhook button to create a webhook for the repository. The Add new webhook page appears.
- A. URL: Enter the URL to your server for the webhook.
- B. Webhook triggers: Pick the events that will trigger the webhook.
- 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.
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 whitelist.
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
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, whitelist these IP addresses:
You can create webhooks for the following events:
- Repository events
- Issue events
- Pull request events
Refer to the event documentation for descriptions and examples of each event payload.