Introduction

This guide is for everyone from complete beginners to experts who want to set up a BitBucket webhook.

You will learn what webhooks are and use a very simple webhook example server written in JavaScript to process webhooks from BitBucket.

Optionally, you could then take that open source code and use it for something more specific.

Prerequisites

We'll be using one programming language, JavaScript for everything.

Its a languages most coders out there will know, but you don't really need to know it finish this guide, as all the code has been written for you.

It may be useful to know JavaScript if you want to take the open source code and then use it as a base for something more specific.

You'll need to have Git and NodeJS installed.

What are webhooks?

A Webhook is a request that a Webhook provider makes to your server.

They use the name web because they are based on HTTP, which is the protocol the web is built on. It runs web applications, websites and APIs.

They are like APIs in reverse. With an API, you make requests to an API provider. Webhooks reverse this flow.

Instead of your code making a HTTP request to the API provider, the Webhook provider makes a HTTP request to you. Your code receives the request, then does something with it.

BitBucket can send you webhook notifications for new commits pushed to your repo, pull request events, repo forks and more.

In addition to BitBucket, there are countless other examples of what other webhook providers can do:

• Mailchimp can send a you webhook when new users sign up to your newsletter
• Facebook messenger can send you a webhook when you receive new messages
• Stripe can send you webhook notifications about new payments

This diagram is a quick high level overview of how webhooks work:

They can automate alot of things that previously would have required lots of polling or manual work, for example instead of polling a service many times an hour to get updates, you can just have that service send you a single webhook request with the info you need.

Now that you know the meaning of the word webhook, lets set up a simple webhook server.

Get the code

We'll use my polyglot webhook example server, written in JavaScript.

Clone the source: git clone https://github.com/cipher-code/polyglot-webhook-example.git.

Go into the polyglot-webhook-example folder by running cd polyglot-webhook-example. Then run npm install to install the dependencies and npm start to start the server. If this does not work, check that you have a clear connection to the internet with no firewalls or restrictions (such as corporate network restrictions).

You should see something like this soon:

> express-api-webhook-example@0.0.1 start /home/robbie/projects/polyglot-webhook-example
> node app.js

Polyglot webhook example server listening at http://localhost:3000

Take a look at app.js

Open app.js. You'll see this:

The top part initialises express, a lightweight framework and web server for JavaScript. When you ran npm install earlier, this automatically installed express using npm.

This code sets up one endpoint, /webhook-receive, which will respond to any HTTP request that is a HTTP GET,POST,PUT or DELETE request.

When a webhook request is received, it outputs request information to the console to let you know.

When you start the app, it will listen on localhost at port 3000.

If you didn't understand any or all of this, don't worry. You can still test your webhooks and learn about this stuff later.

Get a public HTTPS URL for your server

You might remember this output when you started the sever:

Polyglot webhook example server listening at http://localhost:3000

This means the server is listening on localhost, port 3000. If you are new to webhooks, you might think you can configure your webhook endpoint in BitBucket to http://localhost:3000/webhook-receive. There are a couple of issues with that.

The first is that localhost is not a public URL availabe to anyone on the web. localhost is a special address which means your own machine, meaning if you send a request to localhost you are sending a request to your own machine. Similarly, if BitBucket sends a request to localhost they are really just sending a request to their own server.

The second is that its plain unencrypted HTTP and alot of webhook providers won't send you a request unless you are using HTTPS.

The slow, expensive way to get around these issues would be to buy a HTTPS certificate, deploy your code to a server, point a domain you own to it and configure HTTPS. That would take time and you may not even know how to do this. Its also not going to help you test your code locally on your own computer, where you can easily make quick changes that you need to make without deploying.

The fast way is to use a tool I've created called expose, which will give you a public https url with one command.

Install and run expose.sh

For Mac or Linux, go to Expose.sh and copy/paste the installation code shown into a terminal.

For Windows go to Expose.sh, download the binary and put it somewhere in your PATH.

Now that you have expose installed, run expose 3000.

Expose.sh will generate a couple of public expose.sh URLs on a random subdomain. You'll see output like this:

expose 3000
http://m2hh3u.expose.sh is forwarding to localhost:3000
https://m2hh3u.expose.sh is forwarding to localhost:3000

The first URL is HTTP and the second one is HTTPS.

Test your new public HTTPS endpoint

Your web browser can do more than just visit websites. It is also a HTTP client, meaning you can use it to test that your new public HTTPS webhook endpoint is working as expected.

Using the HTTPS url expose generated for you, go to <your https url>/webhook-receive in your browser. Using my own output above, for me this would be https://m2hh3u.expose.sh/webhook-receive.

You should now see a response like this. Im using Firefox, but any browser should work:

If you can see a response in your browser this means you have successfully set up a webhook server with a public HTTPS URL. Save the URL as you'll be using it again later.

If you want to do more advanced testing later, you could use something like Postman or even curl which are also HTTP clients but have more options than a web browser such as being able to send POST and other types of requests.

Configure BitBucket and trigger a webhook request from them

Now that you have a working webhook server with a public HTTPs URL, you need to configure BitBucket and perform an action that will trigger them to send you a request.

To set up a BitBucket webhook, go to your repository. Click Repository Settings, then Webhooks. Click Create Webhook.

Enter a short description into Title, such as "Test BitBucket Webhook". Using the HTTPS url expose.sh generated for you, enter <your https url>/webhook-receive into the URL field (or just copy what you had in the address bar of your browser when you did the test earlier, its this URL). Finally, click Create to create the webhook.

Once this is done, make a commit to git then push the commit to bitbucket. You should soon see a message like this:

Received webhook request to /webhook-receive
Full URL: /webhook-receive

If you see a message like this logged to the console, congratulations!. You have sucessfully set up a webhook integration end to end with BitBucket.

If you do not see a message logged to the console but were able to see a response in your web browser earlier, its either due to misconfiguration or a bug in BitBucket because you already know your side is set up and working. So double check the BitBucket webhook documentation.

Custom subdomains

Because expose by default generates random subdomains, using a custom subdomain (like myapi.expose.sh) would save you from needing to reconfigure a different endpoint in BitBucket after every time you run expose.

Expose.sh is free to use for randomly generated subdomains. If you want to use your own custom subdomains like myapi.expose.sh, you can do this for as little as $4.99/month depending on how many domains you want to use. This also helps me keep the service runnig.

Here's an example using a custom subdomain.

expose 80 as mysite.expose.sh
https://mysite.expose.sh is forwarding to localhost:80
http://mysite.expose.sh is forwarding to localhost:80

You can Sign up here to get custom subdomains.

Conclusion

In the end, webhooks are fairly simple. They are really just regular HTTP requests sent by a webhook provider to your server. Using webhooks, BitBucket can send you lots of useful information when you need it. Because its not you sending the request and you need a public URL, webhook integrations can be tricky to test. Tools like expose can help make testing much easier.