Bitbucket Webhooks Review

Bitbucket is a native Git tool in Atlassian's Open DevOps solution.

When we look at webhook solutions, we’re generally looking for 7 things: signature verification, retries, manual retries, exponential backoff, visibility/logs, event types, and multiple endpoint support. For signature verification, our reference point is the Standard Webhooks specification, which defines the standard headers and signing scheme.

TL;DR:
⬜ Signature Verification
⬜ Retries
⬜ Exponential Backoff
⬜ Manual Retries
✅ Visibility into Logs
✅ Event Types
✅ Multiple Endpoints Support

Signature Verification

Signature Verification is a critical security feature of webhooks. It lets users verify that a webhook was actually sent from the expected source.

There is no mention of the ability to add a signature to the webhook request to allow users to verify its origin.

Retries

Webhook messages often fail. Without retries, users may miss many notifications which results in a bad user experience.

Bitbucket will only retry a failed webhook twice. This results in a bad developer experience as you're going to have your endpoints disabled fairly quickly if they fail and you'll miss events.

Looking to send webhooks at scale?

Exponential Backoff

Exponential backoff is an algorithm that increases the delay between retries exponentially. This ensures that your system won’t get bottleneck from having to re-queue failed webhooks while also giving users time to fix broken endpoints before they burn through all their retry attempts.

There is no mention of the delay between retries but given they only retry twice, its safe to say there is no exponential backoff.

Manual Retries

In the event that a user’s endpoint is failing, its nice to give the developer tasked with debugging the endpoint, the option to initiate a retry manually instead of having to wait for the next scheduled retry (this could be several hours of waiting if they’re close to the end of the retry schedule).

We could not find any mention of triggering retries manually.

Visibility into Logs ✅

Giving users visibility into the delivery logs is critical for troubleshooting/debugging.

Bitbucket has a nice user interface for examining your webhook requests:

They show you the event that triggered the webhook, the time it was triggered, its status, and a link to view more details including the number of times the webhook has been sent.

Event Types ✅

Event types are identifiers denoting the type of message being sent and are the primary way for webhook consumers to configure what events they are interested in receiving.

There is an extensive list of available event types with code samples here: Bitbucket Event Payloads.

Multiple Endpoint Support ✅

Many webhook solutions only allow one endpoint URL to be specified where all messages will be received. By enabling your users to create multiple endpoints, they’ll be able to choose which endpoints receive which messages. Multiple endpoint support and event types go hand in hand.

Bitbucket allows creating of multiple endpoints through the webhooks section in the account settings. There is a limit of 50 webhooks per repository.

Summary

While we liked that Bitbucket included a page dedicated to troubleshooting, we would like to see more features implemented to make their users' lives easier. We'd like to see more retries offered with exponential backoff to give developers time to resolve any failing endpoints before they are disabled. We'd also highly recommend they implement the ability to add a signature to the webhook request to allow their users to verify the origin of the webhook.

If you’re looking to implement world class webhooks, consider trying Svix, the enterprise ready [webhooks service]https://www.svix.com/?utm_source=resources&utm_medium=content). Svix makes it super easy to build a secure, reliable, and scalable webhook solution through an API.