Webhook

Search…
Webhook
How to connect Devices to Datacake using Webhook (from Third-Party IoT Platform such as Pycom PyBytes, Actinius I/O, Blues Wireless Notehub / Notecard - or any other source that can send data via Web)
Introduction
With our new Webhook integration, anything that can relay messages via HTTPS call can be connected to Datacake. This is also called Webhook.
The smart thing about this is that we don't require a structure, but instead provide tools that you can use to accept any format and "decode" it appropriately.
We do this by providing Payload Decoders - a concept well known on LoRaWAN ecosystems.
Add new Device
To add a new Device that can receive data through our Webhook Integration please press on "Add Device" in the fleet overview of your workspace.
This will bring up a modal where you have to select the "API" Device type.
Datacake Product
Now chose "New Product" and provide a new for this product, something like "My Temperature Product" or "My Sensor Template".
What is a product?
Each device on Datacake belongs to a product, which defines:
The dashboard 
The fields in the database 
Payload Decoder 
Routing of the data to the devices
If you add another device and add it to the product we are creating right now, this new device will inherit the dashboard, decoder and database fields from the product.
The data is stored individually.
Dashboard, Decoder and the number of fields in the database will be shared between all devices belonging to the same product.
If you change settings on the product (dashboard, add/remove or change fields) then these changes immediately affect all devices that belong to the product.
Add Device(s)
In the next step you are asked for the devices that are being created and added to the product you defined in the step before. 
Right now we only want to create a single device but this dialog would allow us to create multiple devices and add them all to the same product.
Serial Number
Serial numbers are used to identify devices when ingesting data via Webhook. Datacake auto-generates a Serial Number for you which you at any time later can change to a custom one. 
We leave this set to "Auto-Generate" for now.
Name
Enter a descriptive name for this device here.
Plan
Before we can continue we need to select a plan this device (or multiple devices) will belong to. We do support many different plans and your first two devices are free. 
So in case you are new to Datacake, select "Free". This will let you continue directly.
For more Information on Pricing please visit the following page on our website:
Datacake | Pricing
Create Database Fields
Now that we have created our first device, we open it up by clicking on the List-Entry and use the Navigation Tab-Bar to access its Configuration-View:
Next step is creating a few fields in the database section of this device. So we now scroll down a bit until we reach the "Fields" section:
Here we press on "Add Device".
Using this Modal / View we create the following fields:
Temperature
Humidity
Battery Voltage
So that in the end the Database Section would look like the following:
Product-wide Setting
Please note that the Database Fields are Product-wide Settings!
Even if it seems that we have only attached the fields of the database to the respective device, the fields are stored in the database in the definition of the product.
This means: If you now add another device to the existing product, it will automatically receive the same database fields (but can store its own data).
Forward Data
Now that we have the Database Section set up we can move on and get to the part where the data is being forwarded. 
Webhook URL
Each product on Datacake has its own custom API endpoint.
This URL can be found in the Configuration under the Payload Decoder Settings section.
And it looks a bit like this:
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/
Route Data via Paths
You can add custom paths to your Webhook URL if you want to divide the data of the payload into separate API calls, for example:
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/data/
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/status/
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/diagnostics/
Send Payload
Form Data
If your Content Type is application/x-www-form-urlencoded - You can send the payload as a 
JSON
You can send JSON and parse that into an object.
Query Parameters
You can also send data directly as Query Parameters (in combination with custom Paths and User Payload Data):
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/?device=123&check=true
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/diagnostics/?foo=bar
Set up Payload Decoder
Purpose and Features
With the Payload Decoder you have the possibility with the help of a small piece of JavaScript code to customize the data of the webhook so that you can forward it to Datacake's database.
In summary, a payload decoder has the following features:
Code snippet that is executed when the webhook URL is called.
Access to measured values of all devices of the product.
Routing into the respective device or a group of devices.
Data Flow
The Payload Decoder is connected to the Webhook URL and is executed whenever a message / HTTP call is received via this URL.
Product-Wide
Payload Decoder are product-wide settings!
Since each product on Datacake has its own webhook URL, so is the payload decoder tied to that product.
To forward data from the payload decoder to the respective device, a corresponding ID (serial number) must be passed. We will show you how to do this in the following steps.
Basic Example
Let's get together a very quick example. Imagine your Webhook contains device data encapsulated as a JSON String. So this could look like this:
1
curl --header "Content-Type: application/json" -X POST
2
--data '{"device":"MySerial01","data":{"temp":23.01,"bat":3.21}}'
3
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/
Copied!
Decoder
To extract this data the decoder on Datacake would look like this:
1
function Decoder(request) {
2
​
3
    // Parse JSON into Object
4
    var payload = JSON.parse(request.body);
5
    
6
    // Extract Serial for Routing into Device
7
    var device = payload.device;
8
    
9
    // Load Data from JSON
10
    var data = payload.data;
11
    var temperature = data.temp;
12
    var humidity = data.hum;
13
    var battery = data.bat;
14
    
15
    // Forward Data into Device using Serial
16
    return [
17
        {
18
            device: device,
19
            field: "TEMPERATURE",
20
            value: temperature
21
        },
22
        {
23
            device: device,
24
            field: "HUMIDITY",
25
            value: humidity
26
        },        
27
        {
28
            device: device,
29
            field: "BATTERY_VOLTAGE",
30
            value: battery
31
        },
32
    ];
33
}
Copied!
Debugging
You can test the Decoder using the built in tools that you also find in the Payload Decoder section in the Device Configuration View. 
Simply paste in the JSON as a text into the Body-Field (marked red) and press on "Try Decoder". You can see the Output of the Decoder in the Debug-Fields (marked blue).
If the payload decoder was able to successfully forward data into a device (given correct serial number) you can see the mapping under the "Recognized Measurements" section:
Real Test
You can use CURL or any other URL Calling tool to simulate the API Webhook and test the Decoder under real conditions.
1
curl --header "Content-Type: application/json" -X POST 
2
--data '{"device":"MySerial002","data":{"temp":23.01,"bat":3.21,"hum":54.22}}' 
3
https://api.datacake.co/integrations/api/25f1de28-2630-bea1-be33-c5adc79bef68/
Copied!
Database
After Data has come in you can see this on the Database Fields in the Fields-Section. 
Logging
You can see all incoming Webhooks in the Logs-Section.
Simply click on "Show Logs" which will open a Logging-View showing the last recent Webhook calls.
Device Identification
The following is important. Please read carefully!
Decoders are bound to the URL and the Product the URL belongs to. They are not per Device. So you need to return a routing information so that Datacake can route your data into the actual device.
We do this by providing an additional Key/Value pair when returning data from the payload decoder. You might have already seen that all Payload Decoder Snippets above return a device-Key/Value in their return type, so like:
1
return [
2
    {
3
        device: deviceID, // Serial Number or Device ID
4
        field: "TEMPERATURE",
5
        value: temperature
6
    }
7
];
Copied!
Serial Number
When creating a new API Device Datacake does autogenerate a Serial Number for you. However you can override this Serial Number and paste in Serial Number or any other Identification Info that is also present in the payload of your Webhook.
So imagine your Webhook does contain the following ID:
1
{"id":"MySerial001","temperature":22.01}
Copied!
The important part here is the: "id":"MySerial001" - We can now override the Serial Number of the Device on Datacake and set it to MySerial001.
So in the Configuration-View on the Device in Datacake you find an API Configuration Section that shows the current Serial Number and a Button "Change".
If you click on that you can override the Serial. In the case of this example here we override this to MySerial001.
So once more. Imagine you have the following Webhook Payload:
1
{"id":"MySerial001","temperature":22.01}
Copied!
The Decoder with correct device routing information would look like this.
1
function Decoder(request) {
2
​
3
    var payload = JSON.parse(request.body);
4
​
5
    var deviceID = payload.id;
6
    var temperature = payload.temperature;
7
    
8
    return [
9
        {
10
            device: deviceID, // Serial Number or Device ID
11
            field: "TEMPERATURE",
12
            value: temperature
13
        }
14
    ];
15
    
16
}
Copied!
Hard-coded Identification
What if your Webhook does not contain device identification like a serial number or any other? You can of course hard-code the Device ID in your Decoder, so this would look like this:
1
return [
2
    {
3
        device: "MyHardcodedSerial",
4
        field: "TEMPERATURE",
5
        value: temperature
6
    }
7
];
Copied!
Not on native Integrations
You may have noticed that the concept of Device-ID Identification is not present on the native integrations for LoRaWAN or Particle.io.
This is correct, because here the routing is automated in the backend. This works because the webhook structure is fixed and Datacake always knows where to find the ID (namely DevEUI or Particle Device-ID -Which is also the reason why the serial number for LoRaWAN or Particle is the serial of the respective integration).
Payload Decoder Programming Guide
Decode JSON
Let's assume you are sending JSON as payload:
1
curl --header "Content-Type: application/json" -X POST
2
--data '{"device":"MySerial01","data":{"temp":23.01,"bat":3.21}}'
3
https://api.datacake.co/integrations/api/123456/
Copied!
If you want to decode JSON you can turn 
1
// Parse JSON into Object
2
var payload = JSON.parse(request.body);
3
​
4
// Extract Serial for Routing into Device
5
var device = payload.device;
6
​
7
// Load Data from JSON
8
var data = payload.data;
9
var temperature = data.temp;
10
var battery = data.bat;
11
​
12
// Forward Data into Device using Serial
13
return [
14
    {
15
        device: device,
16
        field: "TEMPERATURE",
17
        value: temperature
18
    },
19
    {
20
        device: device,
21
        field: "BATTERY",
22
        value: battery
23
    },
24
];
Copied!
Decode Form Data and Requests
if your Content Type is: application/x-www-form-urlencoded - you can send a body like this:
1
deviceid=MyDeviceID123&temperature=23.01&battery=3.43
Copied!
The request-Object in your Payload Decoder will hold already parsed Objects of this payload which you can access in the following way:
1
function Decoder(request) {
2
​
3
    var payload = request["POST"];
4
​
5
    var deviceID = payload.deviceid[0];
6
    var battery = payload.battery[0];
7
    var temperature = payload.temperature[0];
8
    
9
    return [
10
        {
11
            device: deviceID, // Serial Number or Device ID
12
            field: "TEMPERATURE",
13
            value: temperature
14
        },
15
        {
16
            device: deviceID, // Serial Number or Device ID
17
            field: "BATTERY",
18
            value: battery
19
        }
20
    ];
21
    
22
}
Copied!
Decode Query Parameters
If you are Sending Data as Query Parameters like this:
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/?device=123&check=true
The following snippet shows you how to access those in the Decoder:
1
function Decoder(request) {
2
​
3
    var payload = request["GET"];
4
​
5
    var deviceID = payload.device[0];
6
    var temperature = payload.temperature[0];
7
    
8
    return [
9
        {
10
            device: deviceID, // Serial Number or Device ID
11
            field: "TEMPERATURE",
12
            value: temperature
13
        }
14
    ];
15
    
16
}
Copied!
Combining Query & Payload
If you want to combine URL Query Parameters with Form Encoded Data or any other Payload you can do this using the following snippet:
1
function Decoder(request) {
2
​
3
    // query is always GET - even on POST
4
    var queryParameters = request["GET"];
5
    
6
    // payload is on POST only
7
    var payloadData = request["POST"];
8
​
9
    ...
10
    
11
}
Copied!
Decode Methods
You can query info about the current Method and use this as a routing info for your payload decoder:
1
function Decoder(request) {
2
​
3
    if (request.method === "POST") {
4
    
5
        // Do Stuff when "POST"
6
        
7
    } else if (request.method === "GET") {
8
    
9
        // Do Stuff when "GET"
10
    }
11
    
12
    ...
13
}
Copied!
Route URL Paths
You can use Custom URL Endings on your API Webhook URL to separate Actions inside the Payload decoder. So let's assume you are using the following URL Endings:
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/data/
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/status/
https://api.datacake.co/integrations/api/2de1c5ade79bcef8/diagnostics/
Here is how you use these in a Payload Decoder:
1
function Decoder(request) {
2
    
3
    var data = JSON.parse(request.body);
4
    
5
    var urlElements = request.path.split('/');
6
    var lastURLSegment = urlElements[urlElements.length-2];
7
    
8
    if (lastURLSegment === "data") {
9
    
10
    } else if (lastURLSegment === "status") {
11
    
12
    } else if (lastURLSegment === "diagnostics") {
13
    
14
    }
15
    
16
}
Copied!
Return Multiple Devices
If your Webhook Payload contains data for multiple devices you can return them all in a single call.
Webhook
Imagine your Webhook is sending JSON Data that contains payload for multiple devices, structured something like this.
1
[
2
    {"id":"MySerial001","temperature":22.01},
3
    {"id":"MySerial002","temperature":22.01},
4
    {"id":"MySerial003","temperature":22.01}
5
]
Copied!
Decoder
In this case the Decoder would look something like this:
1
function Decoder(request) {
2
​
3
    var devices = JSON.parse(request.body);
4
    
5
    for (var i = 0; i < devices.length; i++) {
6
    
7
        var device = devices[i];
8
        
9
        datacakeFields.push({
10
            device: device.id, // Serial Number or Device ID
11
            field: "TEMPERATURE",
12
            value: device.temperature        
13
        });
14
        
15
    }
16
    
17
    return datacakeFields;
18
}
Copied!
Device Identification
Please make sure that the JSON-Data contains information that can be used to identify the devices in the payload decoder (eg. Serial Number).
Recording Historical Data
Webhook
Lets assume you have a temperature sensing device that collects four individual measurments (over a time of 15 Minutes) and then sends them as a combined message (each hour).
The payload would look like this:
1
{"id":"MySerial001","temperatures":[21.23, 22.34, 45.43, 56.40]}
Copied!
Decoder
Our Decoders can return timestamps so you can backfill the Database Fields. This would look something like the following snippet:
1
function Decoder(request) {
2
​
3
    var devices = JSON.parse(request.body);
4
​
5
    var deviceID = payload.id;
6
    var temperatures = payload.temperatures;
7
    
8
    // current Unix Timestamp
9
    var timestamp = Math.floor(Date.now() / 1000);
10
    
11
    for (var i = 0; i < temperatures.length; i++) {
12
    
13
        var temperature = temperatures[i];
14
        
15
        datacakeFields.push({
16
            device: deviceID, // Serial Number or Device ID
17
            field: "TEMPERATURE",
18
            value: temperature
19
            timestamp: timestamp
20
        });
21
        
22
        // decrease Timestamp 15 Minutes (go back in time)
23
        timestamp = timestamp - (15 * 60);
24
        
25
    }
26
    
27
    return datacakeFields;
28
}
Copied!
Access Request Object
Let's assume you are calling the following Webhook:
1
curl -X POST -d 'post=parameter' 
2
https://api.datacake.co/integrations/api/123456/optionalsubpath?foo=bar
Copied!
In your Payload Decoder you have the access to the following parameters of your HTTP Webhook everytime there is a Webhook call happening:
1
{
2
    "method": "POST",
3
    "GET": {
4
        "foo": ["bar"]
5
    },
6
    "POST": {
7
        "post": ["parameter"]
8
    },
9
    "body": "post=parameter",
10
    "headers": {
11
        "Content-Length": "14",
12
        "Content-Type": "application/x-www-form-urlencoded"
13
    },
14
    "path": "/integrations/api/123456/optionalsubpath"
15
}
Copied!
Particle Tracker One
Next - API
Record Measurements via API
Last modified 7mo ago