January 10, 2021
This guide is for everyone from complete beginners to experts who want to set up a BitBucket webhook.
Optionally, you could then take that open source code and use it for something more specific.
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.
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
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
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:
> firstname.lastname@example.org 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
The top part initialises
npm install earlier, this automatically installed express using
This code sets up one endpoint,
/webhook-receive, which will respond to any HTTP request that is a HTTP
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
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
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.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
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.
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.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.
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.