Measurement webhooks

Configuration

Webhooks configuration can be accessed by users with Administrator or Manager permissions.

In order to configure webhooks, from the menu on the left, select Settings (the gear icon), and then Webhooks.

On the list you can see all the sensors added to your organization along with the information, if the webhook is set for this device, when the webhook was triggered last time and what was the received response. To add a webhook, click on the + button in the URL column and add the URL, to which the incoming measurements will be pushed. The URL must contain “http://” or “https://” prefix and at least three characters (including the dots in the URL).

It is also possible to add up to five user defined headers to the webhook configuration. These headers will be added to each frame sent over webhooks. For each of the custom headers users can define a pair “Name” and “Value”, maximum length of each of these parameters is 512 characters.

To add custom headers to the webhook, check the box next to the “Use custom headers” and configure the headers according to your needs.

Before saving the webhook, you can test it by pressing the TEST button. Efento Cloud will send a mock payload to the set address and display the server’s response.

Once a webhook is set, it will be visible on the list of sensors along with the information on when it was triggered and status, based on the response received from the third party application.

There are six possible statuses of a webhook:

  • New - webhook was configured but never triggered yet

  • OK - webhook was triggered and proper response (2XX, e.g. 200, 201) received from the server

  • No response - webhook was triggered, but the server did not return any response (timeout)

  • Error - webhook was triggered but the server returned response with the code different then 2XX

  • Temporarily disabled - Efento Cloud temporarily disabled the webhook. This happens, if the server did not return any response to the webhook five times in a row. In that case Efento Cloud automatically disables the webhook for six hours. After that time the webhook is automatically enabled again.

  • Disabled - If Efento Cloud does not receive any response from the server to which it pushes the data for 30 hours, the webhook is automatically disabled and has to be manually enabled by the user.

To edit or remove a webhook, click on its URL. The webhook configuration dashboard allows also searching for the specified measurement point on the webhooks list, filtering the webhooks by their statuses (Filters -> Status) and filtering the measurement points based on the webhook assignment (Filters -> webhook configured? -> Yes / No).

Payload

Efento Cloud sends the measurements as JSON using the POST method. The JSON contains:

  • Information about measurement point (ID and its name in Efento Cloud)

  • Serial number of the sensor that took the measurements

  • Channel types

  • Time range of the measurements (from, to)

  • Measurement values along with the measurement period, timestamps and statuses

In order to minimize the payload sent over the webhooks, Efento Cloud sends the measurements in the form of Measurement Events. A Measurement Event occurs, if there was a change in the measurement value, measurement period or measurement status.

When receiving the data, the third party application has to extrapolate the measurements. Examples of data extrapolation are included in this user manual in chapter Extrapolating the measurements.

JSON is structured as below:

deviceSerialNumber
Serial number of the sensor that took the measurements

firstMeasurementTimestamp

Timestamp (UTC) of the first measurement in the batch

lastMeasurementTimestamp

Timestamp (UTC) of the last measurement in the batch

measurementPointId

ID of the measurement point in Efento Cloud

measurementPointName

Name of the measurement point in Efento Cloud

measurementsReceivedAt

Timestamp (UTC) when Efento Cloud received the measurements batch that is sent over webhook

signalStrength

Signal strength reported by the sensor

batteryStatus

Status of sensor’s battery, possible values: - OK - battery level is good, - LOW - battery needs to be replaced

measurementsEvents

Array of the sensor’s channels. Contains measurements taken by the sensor on all its channels.

channelNumber

Channel number (a single sensor can have up to 6 channels)

channelType

Channel type. Units of the measurement (“value” field) are based on the channel type.

events

Array of Measurement Events - measurements taken by a sensor on a particular channel. Includes only the measurements that have different values than the previous ones.

timestamp

Measurement Event timestamp (UTC)

value

Measurement value. Depending on the “status” value: - for statuses from OK group, value of the measurement, unit based on the “channelType” - for status MISSING, the value is always NULL - for status ERROR, value contains the error code

period

Measurement period set on the sensor

status

Status of the measurement. Available statuses: - OK - default status. There are no issues with the measurement - MISSING - there is a gap in the measurements received by Efento Cloud (e.g. a sensor was out of the gateway’s range and did not resent the data yet) - OK_CALIBRATION_REQUIRED - used for VOC (IAQ) sensors and pulse counters. Information that the measured values may be inaccurate, as the device needs to perform auto-calibration (VOC sensor) or manual calibration (pulse counters) - OK_ACCURACY_LOW - used only for VOC (IAQ) sensors. Information that the measured values may have poor accuracy, as the device is performing auto-calibration - OK_ACCURACY_HIGH - used only for VOC (IAQ) sensors. Information that the measured values may have good - ERROR - the measurement sent by the sensor is out of the specified range. This usually mean that there is a hardware issue with the sensor (e.g. the probe is not connected or the sensor is physically damaged) - INCOMPLETE - used only for pulse counters, before the first measurement period is completed - OUT_OF_RANGE - the measurement taken by a sensor is out of the defined range. This usually indicates a hardware issue - NOT_SYNCHRONIZED - used only for pulse counters. This status indicates that the user did not set the initial value of the pulse counter

Extrapolating the measurements

In order to minimize the payload sent over the webhooks, Efento Cloud sends the measurements in the form of Measurement Events. A Measurement Event occurs, if there was a change in the measurement value, measurement period or measurement status.

This means that if the value measured by the sensor did not change, it is not included in the JSON. The third party application that receives the data from Efento Cloud has to extrapolate the measurement based on the measurement period (“period” field in the JSON’s objects “events”) and the time range of measurements (“firstMeasurementTimestamp”, “lastMeasurementTimestamp”). Examples:

Changes in the “value” field

The measurement period of the sensor is set to 60 seconds.

  1. At 12:00:00 the sensor measured 20°C

  2. At 12:01:00 the sensor measured 20°C

  3. At 12:02:00 the sensor measured 20°C

  4. At 12:03:00 the sensor measured 21°C

  5. At 12:04:00 the sensor measured 21°C

Data sent over the webhook contains: 12:00:00 value: 20°C and 12:03:00 value: 21°C, as the measurement values at 12:01:00 and 12:02:00 were the same as the one at 12:00:00 and the value at 12:04:00 was the same as the one at 12:03:00. The JSON will look as below:

Changes in the “period” field

Initially, the measurement period of the sensor is set to 180 seconds. Measurement period was later on changed to 60 seconds.

  1. At 12:00:00 the sensor measured 20°C

  2. At 12:01:00 the measurement period changed to 60 seconds and the sensor measured 20°C

  3. At 12:02:00 the sensor measured 20°C

  4. At 12:03:00 the sensor measured 21°C

Data sent over the webhook contains 12:00:00 value: 20°C, 12:01:00 value: 20°C, 12:03:00 value: 21°C. As there was a change in the measurement period at 12:01:00. The “events” array in the JSON will look as below:

Changes in the “status” field

The measurement period of the sensor is set to 60 seconds.

  1. At 12:00:00 the sensor measured 20°C

  2. At 12:01:00 the sensor’s probe was unplugged and the device was not able to take a measurement

  3. At 12:05:00 the sensor’s probe was plugged again and the sensor measured 20°C

Data sent over the webhook contains: 12:00:00 value: 20°C (status: OK), 12:01:00 value: 10000 (status: ERROR), 12:05:00 value: 20°C (status: OK). The “events” array in the JSON will look as below:

None of the fields (“value”, “period”, “status”) did not change their values in the whole batch of the measurements sent over webhook

In this case the “events” array will only contain a single value. This means that the value was the same for the whole time period defined by "firstMeasurementTimestamp" and "lastMeasurementTimestamp". The JSON will look as below:

In this example, the sensor took 43 measurements (11:00:00, 11:01:00, 11:02:00, …, 11:42:00), but as their value was always 20°C, only the first one was included in the JSON.

Limitations

There are few limitations that should be considered when using the webhook service:

  • It is possible to configure one webhook per measurement point

  • The application, to which Efento Cloud sends the data, needs to respond within 10 seconds from the moment when the webhook was triggered

  • Efento Cloud does not resend the measurements. If the application that receives the data was not responding the data will not be resent and needs to be pulled using Efento Cloud API

  • The only accepted response codes, confirming that the measurements were received are 2XX codes (200, 201, etc.)

  • The maximum URL length is 500 characters, including the mandatory “http://” or “https://” prefixes

  • It is possible to configure up to five custom headers per webhook

  • It is impossible to change the structure of the payload (JSON) sent

PreviousTheme settingsNextAlert webhooks

Last updated