Skip to content

Configuring a Sample Webhook & Server

GitKraken Boards and GitKraken Timelines will sunset at the end of 2022. Please read our full announcement and FAQ to learn more.

Now that you know how to set up a webhook inside of GitKraken Boards, we'll walk you through setting up a simple Express server to handle incoming payloads.

If you wish to follow along on your own computer, you can download the complete source code for this project from our GitHub repository.

Setting up the server

Prerequisites: * Node v6 or greater * ngrok

After cloning or downloading the repository linked above. You will need to install the needed dependencies to your local machine. This can be done with yarn or npm i.

The server provided is configured to display the event type as well as the body of the payload message. The source code provided also demonstrates how you can utilize the `x-gk-signature` header to verify the received payload is from GitKraken Boards:

const createSignature = (buf) => {
  const hmac = crypto.createHmac('sha1', WEBHOOK_SECRET);
  hmac.update(buf, 'utf-8');
  return 'sha1=' + hmac.digest('hex');

const verifyWebhookSignature = (req, res, next) => {
  const signature = createSignature(req.buf);
  if (signature !== req.headers['x-gk-signature']) {
    return res.status(403).send('invalid signature');


If you are following along and wish to add a secret to your webhook, you will need to configure server.js to have the same secret. To do so, simply set the value of WEBHOOK_SECRET to be a string of your choosing:

const WEBHOOK_SECRET = 'keiflovesgitkraken';

When everything looks good, you can run node . to start the Express server.

We'll come back to this terminal window once our Webhook is configured.

Using ngrok

ngrok is a program that will allow you to expose your local host to the Internet and is free to download.

After installing and setting up ngrok, you can expose your localhost by running ./ngrok http 8080 in the command line (this is the port we are listening on in server.js). You should see something like this in your terminal:

Copy the * URL, it should look similar to This will be used as our payload URL when configuring our GitKraken Boards webhook.

Setting up a webhook

We learned about setting up a webhook earlier. For this example, we will set the Payload URL field to be our ngrok URL, (this URL will be slightly different for you). If you set a value for WEBHOOK_SECRET in server.js, you will also need to configure the same secret in the Secret field.

If your configuration looks similar to the picture above then you should be good to go! Once your webhook is created, try and create a new column in GitKraken Boards. In the console window running your Express server, you should see the payload body:

Since our webhook is setup to watch all event types, try adding a card or a new label to the board! If you want to only listen for specific event types, you can edit always edit your webhook.