How to Test and Replay Bitbucket Webhook Events on localhost with Hookdeck

Bitbucket is a web-based version control repository manager that helps developers collaborate and manage their code. It is primarily used for source code management and provides features such as pull requests, code reviews, issue tracking, wikis, and webhooks which enable developers to receive notifications whenever certain events occur within their repository.

Hookdeck is a webhook management platform that helps developers reliably receive webhooks, manage events and troubleshoot any issues quickly. It also provides the ability to expose a localhost server to the internet. This is useful for testing webhooks, as it allows developers to receive webhook requests from a service like Bitbucket on their local development environment.

In this article, I will show you how to test and replay Bitbucket webhook events on localhost using Hookdeck.

Relaying your Bitbucket webhooks through Hookdeck provides an overall view and keeps track of every event that occurs.

This tutorial demonstrates how to configure a localhost Node.js Express server and use Hookdeck to expose it to the internet. Then, we'll set up a Bitbucket webhook to send requests to the localhost server. I will cover how to:

1. Set up a localhost webhook endpoint
2. Create a Hookdeck connection
3. Create a Bitbucket webhook
4. Test Bitbucket webhook event to localhost app

Set up a localhost webhook endpoint

For this example, we are going to use the sample Node.js code from Hookdeck's repository. Feel free to follow up with any application or code you might have.

1. Open up your terminal and clone the repository by running:

git clone https://github.com/hookdeck/nodejs-webhook-server-example.git

2. Change into the cloned directory and install the dependencies.

cd nodejs-webhook-server-example
npm install

3. Start the server by executing:

node server.js

The node.js server starts up on http://localhost:1337. See the list of endpoints in the routes.js file. We make use of the /bitbucket-webhooks-endpoint.

Create a Hookdeck connection

There are several ways of creating a Hookdeck connection (see the guide here).

Create a Hookdeck connection with Hookdeck CLI

1. Install the Hookdeck CLI.
2. Open up your terminal and expose the localhost port with:

hookdeck listen 1337

3. The Hookdeck CLI initiates the creation of a guest account that is to be used.
4. You get prompted to do some basic setup:
   • Create a new source (ex. Bitbucket)
   • Set the path to be forwarded to as /bitbucket-webhooks-endpoint
   • Name the connection label (ex. localhost-app)
5. The connection is created and you are given:
   • A login URL to use for your Hookdeck dashboard
   • The webhook URL needed

6. The same connection can be seen on your Hookdeck online dashboard after following the link.

7. Copy the Bitbucket Source webhook URL. It is to be used later in setting up the Bitbucket webhook listener.

Create a Bitbucket webhook

To create a Bitbucket webhook, follow the steps outlined below.

1. Create or open an existing Bitbucket repository.
2. Navigate to Repository settings > Webhooks on the left sidebar.
3. Click on Add webhook to add a new webhook.
4. Set the Title and URL provided by Hookdeck and Save.

Now, when the specified events occur (push) in the repository, Bitbucket sends a POST request to the Hookdeck endpoint URL, which gets forwarded to your localhost Node.js Express server.

Test Bitbucket webhook event to localhost app

We have successfully set up our localhost server, created a Hookdeck connection, and configured a Bitbucket webhook. Let’s test and trigger the event specified to make sure it is being received in our localhost application.

To trigger the push event, we need to open a new pull request to the repository.

• Upon a successful Bitbucket webhook event trigger, the payload gets relayed by Hookdeck directly to your localhost application.
• On your Hookdeck Request dashboard, you see the requests received with a 200 status code.

A Hookdeck Request is an incoming webhook that Hookdeck receives from an external source. It contains the data that was sent by the external source as is (ex. from Bitbucket).

A Hookdeck Event is the webhook delivered by Hookdeck including configurations or filters applied to a destination (ex. to localhost app).

• Back in the terminal of the localhost application, the successful payload from the webhook is received and logged.

Retrying error or failed events

In case any failed events don’t make it to your destination for some reason, Hookdeck provides you with the ability to retry any attempts to deliver any failed or error event.

To retry a failed event:

• Navigate to the Events tab on the sidebar of your Hookdeck dashboard and click Retry across the failed event.

• This replays the event again from Hookdeck to the local application.

See more details on managing Hookdeck requests and events on the Hookdeck documentation.

Conclusion

In this tutorial, you have learned how to receive Bitbucket webhook events through Hookdeck, a webhook infrastructure for reliable ingestion, to an application running on localhost.

Hookdeck can be used safely to consume, monitor, and troubleshoot your Bitbucket webhooks.