A beginner’s guide to using webhooks

Coming to the Tanda Hackathon this weekend? This guide will step you through how to get started using webhooks with Tanda.

What’s a webhook?

A webhook is a way of you getting an alert when something happens in another system (eg. in Tanda). You can see a list of webhooks we support in our API documentation, or in this handy dandy screenshot:

So for example, when someone is newly employed, your program could get alerted so that you can SMS that person the joke of the day.

And that, in fact, is what we are going to build in this guide.

Ingredients

Here’s what I’ll be using in this guide:

• Tanda. You can create an account here: https://my.tanda.co/try
• Glitch, an online node.js editor & runtime: https://glitch.com. I chose this because it’s reallllly easy to get started and doesn’t require installing anything. If you prefer to work in a different language, you could use another online editor like Cloud 9. If you prefer to work locally, use ngrok so that Tanda can send notifications to your local server.
• Twilio, to send SMS: https://www.twilio.com/
• Postman, for testing things: https://www.getpostman.com/

Step 1: create a server

I start by creating a new project in Glitch. All the magic will happen in my server.js file. For starters I just want to make sure it works, so I remove most of the contents:

Then I click “show” at the top. The page loads, and says “hi”. That’s good!

Next, I want to add an endpoint that can accept messages from Tanda. Basically, I will create a URL here, and then give that URL to Tanda, and tell it to send a message to that URL whenever something happens. To do this, I need to do two things:

1. Add the body-parser middleware. I do this by clicking “package.json” in the left sidebar, then clicking “add package” in the middle, then searching for body-parser, and finally installing it.
2. Add a POST to my server:

console.log based debugging! i’m just going to print any information that any other server sends to this URL.

Finally, I want to get my webhook URL. I do this by clicking the “show” button, which will open a new browser tab with a URL that looks like https://xxxxxxxxx.glitch.me/ (the bit with the xxxx will differ for you). Since my route is at /webhook, my full URL will be https://xxxxxxxxx.glitch.me/webhook. I write this down for later!

Step 2: Add the webhook in Tanda

This one’s pretty easy — I just log in to Tanda and go to https://my.tanda.co/api/webhooks, then click “new webhook”. I’m prompted for a few things:

• The URL, which I got just before.
• A security token, which can be anything — I’ll talk more about this later; leave it blank for now.
• A list of topics. These are the events I want to be notified about. I’m going to start with “user.created”.

I’ll see the webhook once I save:

The next step is to test my webhook. I do this by going to https://my.tanda.co/staff/new to add a new employee:

I click the green create button, then switch over to Glitch. In my activity log at the bottom, there is some new activity!

Step 3: do something cool

So, reflecting on what’s happened so far. I have told Tanda to send me a message every time something happens. And I have set myself up so that I can receive messages, and do something whenever I get one. At the moment the “something” is just writing that message down. The next step will be to do something cooler — in this case, send an SMS.

To do this, I sign up for a Twilio account, and then install the twilio package. This is done through the package.json file, just like I did with body-parser.

Then I write a bit of code, which I mostly copied from Twilio’s docs:

If you want to use this code, you’ll need to add your account SID and auth token from https://www.twilio.com/console. Sorry, I’m not telling you mine! ;)

Finally, I test it again.

And I got an SMS! The message also shows up in Twilio’s outgoing log: https://www.twilio.com/console/sms/dashboard

Finally, the most important bit:

Step 4: do something cooler

If you’ve followed along this far, and want to try something harder, here’s a challenge for you. Rather than sending an SMS when an employee is created, send it when they clock in. At a high level, you will need to do:

• Listen to the clockin.created topic (not user.created)
• Use the Tanda API to find the employee’s phone number when they clock in
• Send an SMS to that phone number

I leave actually doing this as an exercise to the reader!

Now that you’ve gotten this far you should be more than ready to join the fun at the Tanda Hackathon. The challenge is to build something cool that uses webhooks. You can use as few, or as many, events as you like (as long as there’s 1), plus any other tools you can think of. Can’t wait to see what you build!