Managing webhooks in Bitbucket Server
Webhooks provide a way to configure Bitbucket Server to make requests to your server or another external service, whenever certain events occur. A webhook consists of:
- One or more events – the default event is a repository push, but you can select multiple events to trigger the webhook.
- A URL – the endpoint where you want Bitbucket to send the event payloads when a matching event happens.
There are two stages to the webhook: Creating webhooks and Triggering webhooks. Once you've created a webhook for an event, every time that event occurs, Bitbucket sends a payload request that describes the event to the specified URL.
If you're having problems with a webhook, see Troubleshooting webhooks.
On this page:
When to use webhooks
Use webhooks to integrate applications with Bitbucket Server. 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.
- Every time a user pushes commits to a repository, and a mirror synchronizes those changes, you may want to notify your continuous integration system to start a build.
Advantages of webhooks
Without webhooks, you need to poll the API if you want to detect when events occur in Bitbucket Server. However, polling the API is inconvenient, inefficient, and error-prone.
Webhooks mean the API doesn't have to check for the same activity every minute.
Webhook secrets
Webhook secrets are what Bitbucket Server use to authenticate the payload. The secret ensures that between Bitbucket Server and your endpoint, you're able to verify that the contents were not tampered with.
Combined with HTTPS, it helps ensure the message transmitted is the one that Bitbucket Server intended to send.
Securing your webhook
When you define a secret for a webhook, each request is signed via a Hash-based Message Authentication Code (HMAC).
The default for this algorithm is HMACSha256. The header X-Hub-Signature is defined and contains the HMAC.
To authenticate the validity of the message payload, the receiver can perform the HMAC algorithm on the received body with the secret as the key to the HMAC algorithm.
If the results do not match, it may indicate there was a problem with transmission that has caused the message payload to change.
Creating webhooks
You can create a webhook through Bitbucket Server, or with the API. Use the following steps to create a webhook on a repository in Bitbucket. Don't forget the administrators of a repository are the only users who can create a webhook on that repository.
- Open the repository where you want to add the webhook.
- From Repository Settings, click the Webhooks link.
- Click the Create webhook button to create a webhook for the repository.
- Webhook events: Select the event/s to trigger the webhook.
- Enter a Title with a short description, and the URL of the application or server.
(optional) Enter a Secret string of up to 255 characters.
- (optional) Use the Test connection button if required.
- By default, the event for the webhook is a repository push, as demonstrated by the Repository push field.
(Optional) If you don't want the webhook to be active after you create it, remove the checkmark from Active.
Click Create.
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.
Triggering webhooks
When an event associated with a webhook occurs, Bitbucket Server sends a request to the webhook URL containing the event payload.
You can create webhooks for the following events:
Repository events
- Push
- Modified
- Forked
- Comment added to commit
- Comment edited on commit
- Comment deleted on commit
- Mirror synchronized
Pull request events
- Opened
- Approved
- Unapproved
- Needs work
- Merged
- Declined
- Deleted
- Comment added
- Comment edited
- Comment deleted
Troubleshooting webhooks
When you perform an action to trigger a webhook and it doesn't work, you can use the Event log page to figure out what went wrong.
Under Event details in repository settings, you can click view details from the Actions column to access the event log for troubleshooting purposes.
Click through the latest request results (such as Webhook event details) to troubleshoot the issue.
Circuit breaking
To help protect your instance of Bitbucket Server, circuit breaking has been implemented in the Bitbucket webhooks system. This means badly behaving webhooks are skipped for a period of time if they are consistently failing.
By default, when a webhook fails five times, it is considered unhealthy and is skipped.
Initially, it will only be skipped for a short period (10 seconds) but as it continues to fail it will gradually skip for longer periods, up to a max of 10 hours.
A webhook may also be skipped if there are too many webhooks in flight. If there are 250 webhooks being invoked, further requests will be skipped until the number in flight drops below 250.
These limits are entirely configurable if your instance has different requirements. For more information, see Bitbucket Server properties.
If a webhook is being skipped, you can see so via the JMX metrics output by Bitbucket, or via the logs.