Enterprise Webhooks (Part 2)

This tutorial is a continuation of Enterprise Webhooks (Part 1). In this tutorial, we’ll go through the remaining bits that are required to set up and verify your Webhooks.

Prerequisites

Clone the Enterprise Webhooks SDK Repository

You’ll need a code editor such as Sublime Text or Atom. We’ll be using Node.js to develop our app, so you’ll need to make sure you’ve installed it on your machine as well. Now create an empty folder for your project, let’s name it “testApp”. Now, open up your command prompt and run the following command:

git clone https://github.com/messagemedia/enterprise-webhooks-nodejs-sdk.git

This command will create a local copy of the repository in your folder.

Install dependencies

The file is dependent on two packages: express and body-parser. The first package is a simple Node.js framework that we will leverage to set up a server and the second package will be used to read data sent back via POST. To install the dependencies, run the following command:

npm install

This command will install the dependencies listed in the package.json file in your folder.

Start ngrok

We can run Express on port 3000 and pass in the URL (localhost:3000) as a callback URL but the Messages API doesn’t like loopback addresses. We’ll need to expose our local server via a public URL which we can then feed to the Messages API and that’s where ngrok comes into play. Starting ngrok is a piece of cake. Fire up your command line and run the following command:

ngrok http 3000

If all goes well you should see the following:

 

One of ngrok’s niftiest features is a UI to inspect requests. Let’s access it by following the Web Interface URL (127.0.0.1:4040) which can be seen in the screen above.

We’ll use this UI later to find out if our Webhooks have been verified successfully.

Add public key

In the index.js file, replace PUBLIC_KEY_HERE with the key you were provided with earlier when you created a key pair via the Signature Key Management API.

Update webhook URL

If your Webhook URL has a path added to it (eg: /test) then you will have to update the URL in the 27th line inside the update function.

verifier.update("POST /test HTTP/1.1" + date + body);

Moment of truth

It’s time to test! To demonstrate, I’ll be making a request to the Messages API. This is what my body looks like:

{
  "messages": [
    {
     "content": "Hey there!",
     "destination_number": "+61439532036",
     "format": "SMS",
     "delivery_reports": true,
     "callback_url": "http://c8e3b8d9.ngrok.io/hello"
    }
  ]
}

The callback_url property should be the same as the ngrok url.

Once you’ve sent a message, open up the Web Interface and you should see something similar.

Let’s take a minute to talk about what’s happening behind-the-scenes. If you look at my message body, you’ll see that I’ve specified a callback_url as a property. The purpose of the callback_url is to push delivery reports and replies to the URL specified. In case you are wondering, delivery reports or DRs are simply notifications of changes in the status of a message as it is being processed. Whenever a Webhook is triggered, a DR is sent back to the callback_url notifying you of any changes. A Webhook can be triggered by replies as well. You can view the full list of events over here.

Conclusion

Well done – you’ve learned how to create signature keys and use them to verify the authenticity of your Webhooks. Why not take a step back and learn how to create your own Webhook configuration? Read all about it over here.

Resources