This tutorial will show you how to receive data using Enterprise Communications API's webhooks and Node.js. Click the "Start" button below to start the tutorial.Start Tutorial
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:
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.
Next we will configure the web site for your webhook registration in your Enterprise Communications API API Space
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.
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.
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.
To setup the webhook quick start in Heroku for free follow these instructions:
git clone https://github.com/comapi/comapi-quickstart-webhooks-heroku
routes\webhook.jswhere it has >>>YOUR SECRET<<< to match the secret you want to use in your webhook registration
git add . git commit -m "Updated secret" git push heroku master
You can run the project locally by following these steps:
To setup or modify a webhook registration go to the Enterprise Communications API Portal and open the Hub -> Webhooks page, shown below:
heroku opentakes you to
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
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.
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.
This is the web method that is used to receive the forwarded events from Enterprise Communications API in JSON format. It job is:
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.
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.
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.
Thanks for taking the time to look through the tutorial, to find out more visit our full documentation.