Introduction

This Bulkdata Webhooks smart module is a Smart Module that transfers arbitrary binary data from MODE Devices by making webhook calls to your server.

Setting up Bulkdata Webhooks Smart Module

ONE | In the Developer Console, navigate to the Smart Modules page and select +NEW. Click +ADD on the section for Bulkdata Webhooks.

TWO | Fill out the "New Bulkdata Webhooks Smart Module" form, then click Save.

How to send the data

Send arbitrary data from devices

You can send any kind of data which can be represented as a byte sequence by MQTT with Bulk Data topic. Please read How to use MQTT with MODE if you are not familiar.

Receiving the binary data

This section describes what kind of data the BulkData Webhooks smart module sends to your webhook handler application.

Following is basic HTTP request information.

• TitleValueDescription
• HTTP MethodPOSTIn general, the webhook uses the POST HTTP method.
• Content-typeapplication/octet-streamThis indicates content is an assortment of bytes
• Body’s data typeBinary dataThe body can be any opaque data

The MODE custom headers

The BulkData Webhooks smart module includes metadata in HTTP headers when calling a webhook. The header descriptions are as follows.

• NameExample ValueDescription
• X-Mode-Signatured3b07384d113edec49eaa6238ad5ff00This signature is for verifying the caller's authenticity. We will explain below.
• X-Mode-DeviceID3600ID of the device that sent the event.
• X-Mode-ModuleIDbulkDataWebhookModule ID of the Bulkdata Webhooks module making the webhook call
• X-Mode-ProjectID10ID of the project associated with the webhook call
• X-Mode-HomeID10ID of the home associated with the webhook call

Webhook Signature Verification

Anyone can call your webhook URL and post a request. To verify that the request is coming from MODE, your webhooks handler should check the X-Mode-Signature header in the request. The signature is calculated by applying the SHA-256 hash algorithm on the webhook URL and the request body.

What You Need for Generating the Signature

Let's say the URL of the webhook is as follows: https://www.example.com/handler

On the Developer Console, you can find the secret key associated with the webhook. Let's say the key is: 6idnnaidkdkdr5zq1838jGV

Generating and Matching the Signatures

First you have to create an HMAC using the webhook key. After that, concatenate the webhook URL and the body, calculate the SHA-256 digest, and encode the results using HEX encoding.

Here is a sample code for NodeJS, using the crypto module:

crypto = require("crypto");

var webhook_url = 'https://www.example.com/handler';
var webhook_key = '6idnnaidkdkdr5zq1838jGV';
var body = new Buffer(‘The binary data the BulkDataWebhook smod posted’);

var hmac = crypto.createHmac('sha256', webhook_key);
hmac.update(webhook_url + body);
var generated_signature = hmac.digest('hex');

Your handler needs to compare the generated signature with the string coming from the X-Mode-Signature header string. If it doesn't match the string, the handler should reject the request.

Troubleshooting

You can view the Bulkdata Webhooks Smart Module activities under the "LOGS" section of your Bulkdata Webhooks Smart Module configuration page.

Check if there are log entries at the ERROR level.