We are excited to announce webhook secrets, a powerful new feature that will provide an extra layer of security for your webhook payloads in Bitbucket Cloud. With the ability to add secrets to webhooks, you can now sign webhook payloads to ensure they are coming from Bitbucket Cloud and protect against unauthorized access.
Why is webhook security important?
Webhooks are a crucial component of many developer workflows, allowing you to receive real-time notifications and trigger automated actions in response to events in your repositories. However, without proper security measures in place, webhook payloads can potentially be intercepted or tampered with, potentially leading to security breaches or compromised workflows.
That’s where our new webhook secret feature comes in — it enables you to validate the authenticity of webhook deliveries, ensuring that they are originating from Bitbucket Cloud itself.
Sample use case with Jenkins:
An example of where you might use secured webhooks is when integrating with an on-prem CI/CD solution like Jenkins. Without secured webhooks, you will often need to poll Bitbucket Cloud regularly in order to check for new build-jobs as your security policies may not allow you to rely on IP Whitelisting alone in order to verify the authenticity of webhook requests coming from Bitbucket Cloud. This can often result in issues like being rate-limited by the Bitbucket Cloud API due to polling the relevant endpoints too often.
With secured webhooks, you now have a highly targeted mechanism for verifying the identity of the system sending webhook requests to your on-prem CI/CD solution, meaning you can now more consistently rely on Webhooks to trigger builds rather than periodic polling of the Bitbucket API.
How do webhook secrets work?
When creating or editing a webhook, you can now enter a secret token, which can be a random string of text with high entropy. Alternatively, you can use our “Generate secret” button to let us create a secret token for you. Once you have your secret token, make sure to securely store it on your server.
Bitbucket Cloud will use your secret token to create a HMAC signature, which will be sent to you as the value of the X-Hub-Signature header with each payload. The signature is calculated based on the payload contents, your secret token, and a hashing algorithm (sha256).
In your server-side code that handles webhook deliveries, you can calculate a HMAC of the payload using the same hash algorithm and your stored secret token. Then, compare the calculated HMAC with the HMAC received from Bitbucket Cloud to ensure they match. This ensures that the payload is legitimate and has not been tampered with.
To make implementation easier, we have provided example code in Java and Python that demonstrates how to verify the webhook signatures. You can refer to these examples to implement the HMAC verification in your preferred programming language.
Robust security, easy adoption
By enabling webhook secret validation, you add an additional layer of security to your webhook payloads, giving you peace of mind that only legitimate payloads from Bitbucket Cloud will be processed. This helps protect against potential security vulnerabilities and ensures the integrity of your automated workflows.
To start using this new feature, simply navigate to the repository settings in Bitbucket, select the “Webhooks” option, and then create or edit a webhook. It is recommended to add a secret to all your webhooks to maximize security.
Remember to securely store your secret token and follow the best practices for key management. Never hardcode the token into your application or push it to a repository, as this could compromise the security integrity of your webhooks.
For more details on how to use webhook secrets, including step-by-step instructions and example code, check out our documentation. And as always, if you have any questions or feedback, feel free to reach out to us via Community.
