Articles on: cThings Cloud

How do I create a webhook?


What are webhooks?


Webhooks allow you to subscribe to data events for a device in cThings Cloud. Every time data is received for a device, a HTTP request is made to an endpoint defined by you. This endpoint must be secure (HTTPS) and handle the transmitted data as specified below. Your webhook endpoint should look similar to the following example.


https://webhooks-events.cthings.cloud


The following HTTP methods are supported:


  • DELETE
  • GET
  • PATCH
  • POST
  • PUT


Creating a webhook in cThings Cloud


Securing your webhook endpoint


You can optionally secure your webhook endpoint with Basic Authorization or a custom header. We recommend securing your webhook endpoint to prevent unauthorised users from making unsolicited calls to your endpoint.


Basic Authorization requires you to specify a username and password.


Using Basic Authorization to secure your webhook endpoint


Using a custom header requires you to specify a the header key and value. A custom header could be used if securing your endpoint using a bearer token for example.


Using a custom header to secure your webhook endpoint

Receiving data to your webhook endpoint


Our default data payload includes all the data transmitted by the device to cThings Cloud. Below is an example payload.


{
"uuid": "f01ac440-7a0c-22ef-99f1-0a123a385ac9",
"name": "23000000",
"device": "Main Supply",
"route": [
"23000000",
"89880000000000000000"
],
"dtm": "2017-07-01T12:30:00",
"data": {
"energy": {
"description": "Energy",
"unit": "kWh",
"value": 443,
"primary": true,
"typeId": 70
},
"voltage": {
"description": "Voltage",
"unit": "V",
"value": 240,
"primary": false,
"typeId": 180
},
"current": {
"description": "Current",
"unit": "A",
"value": 3,
"primary": false,
"typeId": 183
},
"power": {
"description": "Power",
"unit": "kW",
"value": -0.395,
"primary": false,
"typeId": 186
}
}
}


The top level values are further described below.


Key

Type

Example

Description

uuid

STRING

f01ac440-7a0c-22ef-99f1-0a123a385ac9

A unique identifier for the device

name

STRING

Main Supply

The name of the device, as defined by the user in cThings Cloud

device

STRING

23000000

The device identifier

route

ARRAY

["23000000", "89880000000000000000"]

Any gateways and/or relays via which the data transited

dtm

STRING

2017-07-01T12:30:00

The timestamp of the received data in ISO8601

data

OBJECT

see below

The data sent by the device

The data object is further described below.


Key

Type

Example

Description

description

STRING

Energy

A description of the attribute

unit

STRING

kWh

The unit of the value

value

ANY

443

The value received from the device

primary

BOOLEAN

true

Whether the attribute is the primary attribute, only one attribute should ever be marked as primary

typeId† ††

INTEGER

70

The value type, this is used to normalise data across different device types. For example, all energy attributes should always have a typeId of 70

† A list of types can be obtained using the following API endpoint GET https://api.cthings.cloud/attribute/type
†† Not all attributes have a type as it doesn't always make sense to normalise the data.


Customising the data received by your webhook endpoint


You can customise the data payload sent to your webhook endpoint. When creating a webhook, select Custom Payload.


Customising the data payload for your webhook


The payload formatter uses JavaScript. The default function simply returns the original data object and is displayed below.


function Transform(data) { return data; }


You can make modifications to the function to return a portion of or a modified data object. The below example will return the uuid and energy only.


function Transform(data) {

return {
"uuid": data.uuid,
"energy": data.data.energy
};

}


Testing your webhook


You can test webhooks directly from a device in cThings Cloud. Navigate to your device and select the Configuration tab, towards the bottom of the screen you will see a list of webhooks enabled for you device. To the right of each webhook, beside the Status column, click the clipboard icon. The webhook testing screen will open as illustrated below. Click Test Webhook to test your webhook.


Testing your webhook

Updated on: 20/01/2025

Was this article helpful?

Share your feedback

Cancel

Thank you!