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.
- Module ID: Uniquely identifiable smart module name.
- Description: Description for the new Smart Module.
- Bulk Data Label: Uniquely identifiable name used for uploading the data by MQTT.
- Webhook URL: The destination URL to make webhook call .
- Webhook Key: The Key for generating the signature.
- Headers: (Optional) The headers which you can set arbitrary.
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.
- 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:
On the Developer Console, you can find the secret key associated with the webhook. Let's say the key is:
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.
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.