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.
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.
- 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.
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.
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.
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.
Was this helpful?
Thanks for your feedback!