Receiving data from Enterprise Communications API using Ruby on Rails

This tutorial will show you how to receive data using Enterprise Communications API's webhooks and Ruby on Rails. Click the "Start" button below to start the tutorial.

Start Tutorial

Receiving data from Enterprise Communications API using Ruby on Rails

This tutorial will show you how to receive data using Enterprise Communications API's webhooks and Ruby on Rails. 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:

Setup and configure the example web site

This tutorial solution is a simple web site created using Ruby on Rails that provides a POST URL for Enterprise Communications API to forward events to via it's webhooks. The website also supports a GET request to allow for easy testing to ensure the web site is available.

To setup this project do the following:

Clone the Github repo for the tutorial
Change directory in the repo to the folder: OneAPI\Ruby\Webhook
Download the required dependencies from by running:

gem install rails
bundle install

Once installed you can check all is working by requesting the version of Ruby on Rails by running:

rails --version

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.

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 Ruby on Rails 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-Ruby

Change directory to your cloned repo folder
Create a Heroku app by running:
```
heroku create
```
Update the file app\controllers\application_controller.rb 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 dependencies:
```
bundle install
```
Run the server:
```
heroku local
```
If all has wroked you can browse to http://127.0.0.1:3000/ and the test page for the webhook will be served.

All done

Configuring your SSL certificates (Optional)

Enterprise Communications API will forward data to both HTTP and HTTPS URLs. The tutorial is configured to use HTTP but for production HTTPS is recommended. You can use a 3rd party host such as Heroku who will do SSL offloading for you.

Any SSL certificates used need to be valid for the URL your webhook site is hosted at, and issued by a public certifcate authority such as Verisign.

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:

alt

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

alt

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 have access to the raw HTTP body data. To do this we read the body stream to a string, whilst UTF-8 decoding it.

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, MSMQ 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 log file in the systems temp folder, but for real implementations you would store the data for processing in a queue or distributed cache typically like RabbitMQ, MSMQ 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.

cmVxdWlyZSAndXJpJwpyZXF1aXJlICduZXQvaHR0cCcKcmVxdWlyZSAnb3BlbnNzbCcKCmNsYXNzIEFwcGxpY2F0aW9uQ29udHJvbGxlciA8IEFjdGlvbkNvbnRyb2xsZXI6OkJhc2UKCiAgIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMKICAjIEdFVCBoYW5kbGVyIGZvciB0aGUgSW5kZXggcGFnZQogIGRlZiBpbmRleAogICAgIyBSZW5kZXIgdGhlIHZpZXcKICAgIHJlbmRlciA6aW5kZXgKICBlbmQKCiAgIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjCiAgIyBQT1NUIGhhbmRsZXIgZm9yIHRoZSBJbmRleCBwYWdlLCB0aGUgd2ViaG9vayByZWNlaXZlciBwYWdlCiAgZGVmIGluZGV4UG9zdAogICAgIyBHcmFiIHRoZSBib2R5IGRhdGEKICAgIHJhd19ib2R5ID0gcmVxdWVzdC5yYXdfcG9zdAoKICAgIGlmIChyYXdfYm9keSA9PSBuaWwpCiAgICAgICAgIyBObyBib2R5LCBiYWQgcmVxdWVzdC4KICAgICAgICByZW5kZXIgOmlubGluZSA9PiAiQmFkIHJlcXVlc3QgLSBObyBKU09OIGJvZHkgZm91bmQhIiwgOnN0YXR1cyA9PiA0MDAKICAgICAgICByZXR1cm4KICAgIGVuZAoKICAgICMgV2UgaGF2ZSBhIHJlcXVlc3QgYm9keSBzbyBsZXRzIGxvb2sgYXQgd2hhdCB3ZSBoYXZlCgogICAgIyBGaXJzdCBsZXRzIGVuc3VyZSBpdCBoYXNuJ3QgYmVlbiB0YW1wZXJlZCB3aXRoIGFuZCBpdCBjYW1lIGZyb20gRW50ZXJwcmlzZSBDb21tdW5pY2F0aW9ucyBBUEkKICAgICMgV2UgZG8gdGhpcyBieSBjaGVja2luZyB0aGUgSE1BQyBmcm9tIHRoZSBYLUVudGVycHJpc2UgQ29tbXVuaWNhdGlvbnMgQVBJLVNpZ25hdHVyZSBoZWFkZXIKICAgIHJlcXVlc3RfaG1hYyA9IHJlcXVlc3QuaGVhZGVyc1sieC1jb21hcGktc2lnbmF0dXJlIl0KCiAgICBpZiAocmVxdWVzdF9obWFjID09IG5pbCkKICAgICAgICAjIE5vIEhNQUMsIGludmFsaWQgcmVxdWVzdC4KICAgICAgICByZW5kZXIgOmlubGluZSA9PiAiSW52YWxpZCByZXF1ZXN0OiBObyBITUFDIHZhbHVlIGZvdW5kISIsIDpzdGF0dXMgPT4gNDAxCiAgICAgICAgcmV0dXJuCiAgICBlbHNlCiAgICAgICAgIyBWYWxpZGF0ZSB0aGUgSE1BQywgZW5zdXJlIHlvdSBoYXMgZXhwb3NlZCB0aGUgcmF3Qm9keSwgc2VlIGFwcC5qcyBmb3IgaG93IHRvIGRvIHRoaXMKICAgICAgICBoYXNoID0gY3JlYXRlSG1hY1NoYTEocmF3X2JvZHksICI+Pj5ZT1VSIFNFQ1JFVDw8PCIpCgogICAgICAgIGlmIChyZXF1ZXN0X2htYWMgIT0gaGFzaCkKICAgICAgICAgICAgIyBUaGUgcmVxdWVzdCBpcyBub3QgZnJvbSBFbnRlcnByaXNlIENvbW11bmljYXRpb25zIEFQSSBvciBoYXMgYmVlbiB0YW1wZXJlZCB3aXRoCiAgICAgICAgICAgIHJlbmRlciA6aW5saW5lID0+ICJJbnZhbGlkIHJlcXVlc3Q6IEhNQUMgaGFzaCBjaGVjayBmYWlsZWQhIiwgOnN0YXR1cyA9PiA0MDEKICAgICAgICAgICAgcmV0dXJuCiAgICAgICAgZW5kCiAgICBlbmQKCiAgICAjIFN0b3JlIHRoZSByZWNlaXZlZCBldmVudCBmb3IgbGF0ZXIgcHJvY2Vzc2luZywgcmVtZW1iZXIgeW91IG9ubHkgaGF2ZSAxMCBzZWNzIHRvIHByb2Nlc3MsIGluIHRoaXMgc2ltcGxlIGV4YW1wbGUgd2Ugb3V0cHV0IHRvIHRoZSBjb25zb2xlCiAgICBldmVudE9iaiA9IEpTT04ucGFyc2UocmF3X2JvZHkpCgogICAgcHV0cyAoIiIpICAgICAgICAKICAgIHB1dHMgKCJSZWNlaXZlZCBhICN7ZXZlbnRPYmpbIm5hbWUiXX0gZXZlbnQgaWQ6ICN7ZXZlbnRPYmpbImV2ZW50SWQiXX0iKQogICAgcHV0cyhKU09OLnByZXR0eV91bnBhcnNlKGV2ZW50T2JqKSkgIyBQcmV0dHkgcHV0cyB0aGUgSlNPTgogICAgcHV0cyAoIiIpCgogICAgIyBZb3UgY291bGQgdXNlIHF1ZXVpbmcgdGVjaCBzdWNoIGFzIFJhYmJpdE1RLCBvciBwb3NzaWJseSBhIGRpc3RyaWJ1dGVkIGNhY2hlIHN1Y2ggYXMgUmVkaXMgICAgICAgCgogICAgIyBTZW5kIHdvcmtlZAogICAgcmVuZGVyIDppbmxpbmUgPT4gIkRhdGEgYWNjZXB0ZWQiLCA6c3RhdHVzID0+IDIwMAogICAgcmV0dXJuCiAgZW5kCgogICMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMKICBwcml2YXRlCgogICMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMjIyMKICAjIENyZWF0ZSBhIEhNQUMgaGFzaCBzaW5nIFNIQS0xCiAgZGVmIGNyZWF0ZUhtYWNTaGExKGRhdGEsIGtleSkKICAgIGRpZ2VzdCA9IE9wZW5TU0w6OkRpZ2VzdC5uZXcoJ3NoYTEnKQogICAgaG1hYyA9IE9wZW5TU0w6OkhNQUMuaGV4ZGlnZXN0KGRpZ2VzdCwga2V5LCBkYXRhKQoKICAgIHJldHVybiBobWFjCiAgZW5kCgplbmQ=