Receiving data from Enterprise Communications API using Node.js

This tutorial will show you how to receive data using Enterprise Communications API's webhooks and Node.js. It covers off the basics for receiving and validating that the data has come from Enterprise Communications API and has not been tampered with.

The tutorial's navigation controls are located above this text. Use to move to the next step of the tutorial. Use to move to the previous step of the tutorial (if there is one). Use to see an overview of all the steps in the tutorial.

To begin with you will need the following prerequisites installed:

• Node.js
• NPM (Installed with Node.js)

Setup and configure the example web site

In the tutotials folder you will find a simple web site created using Express that will receive POSTed data over SSL, and process it to ensure it was from Enterprise Communications API and not tampered with. setup this project do the following:

• Clone the Github repo for the tutorial
• Open a console / shell and change to the cloned repos folder
• Download the required dependencies from NPM by running:

npm install

Next we will configure the web site for your webhook registration in your Enterprise Communications API API Space

Setup your shared secret

When you setup a webhook registration with Enterprise Communications API you will need to specify a secret which is a phrase or password used as the key when creating a HMAC SHA-1 hash for your forwarded notifications.

You need to update the code where it has >>>YOUR SECRET<<< to match the secret you want to use in your webhook registration, so that the receiving page can validate any data received by comaring the hash it generates with that Enterprise Communications API set and stored in the X-Enterprise Communications API-Signature HTTP header.

If the HMAC hash does not match then the data should not be trusted and rejected with a HTTP 401 - Unauthorised response.

Configuring your SSL certificates (Optional)

Enterprise Communications API will forward data to both HTTP and HTTPS URLs. The tutorial is configured to use SSL but you must replace the supplied certficate and private key with your own, or even easier use a 3rd party host such as Heroku who will do SSL offloading for you.

The SSL certificate needs to be valid for the URL your webhook site is hosted at, and issued by a public certifcate authority such as Verisign.

If you wish to use SSL please replace the key.pem and cert.pem files with your own for the domain in the ssl folder and set the passphrase in the www.js file to the password of your private key file.

Hosting your webhook page

You must now deploy the webhook website to a server and ensure it is publically accessible.

A good option for easy RnD is to use Heroku, as accounts are free and you can spin up a Node.JS project in minutes, see below for instructions.

Test by browsing to the webhook page which should return a basic web page, and make a note of your URL so it can be confirgured as a webhook in Enterprise Communications API.

Hosting in Heroku

To setup the webhook quick start in Heroku for free follow these instructions:

• Sign-up for a free account with Heroku

• Download and install Heroku
• Open a CLI console
• Ensure Heroku has your credentials by running the following command and entering them:

  heroku login
  

• Clone the following Github repo:

  git clone https://github.com/comapi/comapi-quickstart-webhooks-heroku
  

• Change directory to your cloned repo folder
• Create a Heroku app by running:

  heroku create
  

• Update the file routes\webhook.js where it has >>>YOUR SECRET<<< to match the secret you want to use in your webhook registration
• Publish the code to Heroku with these commands:

  git add .
  git commit -m "Updated secret"
  git push heroku master
  

• Now test the deployment worked by running:

  heroku open
  

• If you have issues you can see the logs by running:

  heroku logs
  

Running locally

You can run the project locally by following these steps:

• Change directory to your cloned repo folder
• Install NPM dependencies:

  npm install
  

• Run the server:

  heroku local
  

All done

Setting up your webhook in Enterprise Communications API

To setup or modify a webhook registration go to the Enterprise Communications API Portal and open the Hub -> Webhooks page, shown below:

Adding a new webhook registration

• Click the Add new Webhook button and fill in the wizard that pops up
• Fill in the Name field with a meaningful name for your webhook e.g. Analytics feed
• Add your URL to your webhook page to the Target URL field, if using Heroku this is the URL that the command heroku open takes you to
• Add a secret to be used to hash your events, so that you can verify we sent the data and it hasn't been tampered with (See the security section above)
• Choose your events to receive, in this case choose the Message events, best practice is to only select those events that you need for performance reasons
• Scroll down and click Create to create the webhook registration

Testing the webhook

For this test please ensure you have ticked the message.sent event on your webhook subscription.

We need to send a message via the Enterprise Communications API to trigger a message.sent event to be sent to our webhook. To do this you can either use a tool such as Postman and our API docs or follow our simple SMS sending tutorial.

Once you have sent your message check the console output on your server hosting your webhook page; you should see the event data similar to the image below. If you used Heroku then you can do this by running:

heroku logs --tail

Understanding the code

Exposing the raw body data

In order to calculate the HMAC SHA-1 hash to compare with one passed in the x-comapi-signature header we need to ensure that Express exposes it. To do this we must tweak the processing of the body middleware to add a rawBody property to the req object express passes to the routes.

The highlighted code perfroms this task.

Adding a GET handler

Officially Enterprise Communications API only requires your web page to handle HTTP POSTs, but to make it easier to test whether your webhook page is available we have added a basic HTTP GET handler that just returns a basic static web page.

Adding a POST handler

This is the web method that is used to receive the forwarded events from Enterprise Communications API in JSON format. It job is:

• Validate that the data is from Enterprise Communications API and hasn't been tampered with using the HMAC validation
• Store the received event for processing ayschronously to ensure the fastest response possible
• Acknowledge the data receipt within 10 seconds, otherwise Enterprise Communications API will assume a timeout

Note: We strongly advise doing any data processing of events asynchronously to ensure that the data can be passed to your systems as fast a possible. Suitable technologies to use for passing the received data into system are queues and distributed caches such as RabbitMQ and Redis.

HMAC Validation

Enterprise Communications API uses HMAC SHA-1 validation to ensure you can tell that data has come from Enterprise Communications API and hasn't been tampered with. This is achieved by Enterprise Communications API creating a hash value using the HMAC SHA-1 algorithm using a secret password or phrase as the encryption key. This secret key can be anything you like and must be configured against your webhook registration in Enterprise Communications API.

The highlighted code takes the hash values from the HTTP header x-comapi-signature and then calculates an equivalent hash using the HMAC SHA-1 algorithm with the raw body data and the same secret key you entered in the webhook registration. The two hash values will be identical if the data came from Enterprise Communications API and hasn't been tampered with.

If the hash values do not match, do not accept the data and return a HTTP 401 Unauthorised return code. If the values match you can trust the data is from Enterprise Communications API and hasn't been tampered with, and continue to store it for processing.

Event storage

In this basic example code we are simply dumping the event data to the system console, but for real implementations you would store the data for processing in a queue or distributed cache typically like RabbitMQ or Redis.

The queue processors will be responsible for checking the revision property of the events to see if the event should be discarded or not as it is no longer valid. A good example of this would to track the messageId and revision when receiving receipts for message sends, as messages go through multiple statuses such as sent > delivered > read, and as the ordering of these events cannot be guarantied the revision property can be used to ensure obsolete events can be recognised.

In the message receipt use case the revision property is guarantied to be higher in later events, so the revision property value for the read event would be higher than the revision property values on the sent and delivered events.

All done

Thanks for taking the time to look through the tutorial, to find out more visit our full documentation.