Getting started with Webhooks

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

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 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.

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.



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.

Updated on: 29/11/2024