Event Webhook Specification

• Last updated: 2018-09-20
• Current version: 2

TOC

Spec Example

Full sync events are transmitted on starting, synchronizing (either manually or automatically using the mobile app), and completing sessions by connecting to the data logger. Ping events are transmitted automatically by the mobile app when in proximity of the device.

Full sync

{
    "apiVersion": 2,
    "eventID": "A1B2C3D4E5F6G7H8",
    "eventType": "fullsync",
    "isRetransmission": false,
    "data": {
        "macAddress": "ABC123DEF456",
        "sessionID": "CBA321987ZYX",
        "eventType": "fullsync",
        "eventTime": 1433522419,
        "activationTime": 1433521019,
        "startLoggingTime": 1433521019,
        "stopLoggingTime": 1433522419,
        "latitude": 29.6536423,
        "longitude": -82.3292396,
        "name": "InitTest1",
        "productNumber": 2,
        "gracePeriod": 40,
        "loggingInterval": 42,
        "firmwareVersion": "1.0.1.1",
        "batteryLevel": 25,
        "sensors": [
            {
                "sensorType": "temperature",
                "highResLoggingTrigger": 0.5,
                "currentReading": 23.9,
                "minThreshold": 20,
                "maxThreshold": 50,
                "coefficients": [
                    0,
                    12,
                    45,
                    125,
                    200,
                    255
                ],
                "sensorData": [
                    {
                        "time": 1433521019,
                        "value": 11
                    },
                    {
                        "time": 1433521119,
                        "value": 22
                    },
                    {
                        "time": 1433521219,
                        "value": 33
                    },
                    {
                        "time": 1433521319,
                        "value": 44
                    }
                ]
            },
            {
                "sensorType": "humidity",
                "highResLoggingTrigger": 3,
                "currentReading": 61.0,
                "coefficients": [
                    0,
                    2,
                    4,
                    8
                ],
                "minThreshold": 0,
                "maxThreshold": 10,
                "sensorData": [
                    {
                        "time": 1433521019,
                        "value": 55
                    },
                    {
                        "time": 1433521119,
                        "value": 66
                    },
                    {
                        "time": 1433521219,
                        "value": 77
                    },
                    {
                        "time": 1433521319,
                        "value": 88
                    }
                ]
            }
        ],
        "deviceEvents": [
            {
                "T": 1433521017,
                "ID": 2
            },
            {
                "T": 1433556736,
                "ID": 5
            }
        ]
    }
}

Ping

{
    "apiVersion": 2,
    "eventID": "a87ff679a2f3e71d",
    "eventType": "ping",
    "isRetransmission": false,
    "data": {
        "macAddress": "1234567890ab",
        "sessionID": "TEST1234567890AB",
        "eventTime": 1451274620,
        "eventType": "ping",
        "latitude": 30.25973254159176,
        "longitude": -97.78942891940008,
        "name": "TestPod",
        "productNumber": 1,
        "sensors": [
            {
                "sensorType": "temperature",
                "currentReading": 22.98
            }, {
                "sensorType": "humidity",
                "currentReading": 48.6
            }
        ]
    }
}

Notes

• Each request will be a POST, with the above payload in the body of the request. The Content-Type will be application/json.
• All timestamps are number of seconds since Jan. 1, 1970 00:00:00 GMT (also known as the Unix epoch or Unix time).
• In order for the event to be considered delivered, the endpoint must respond with a 2xx HTTP response code within 15 seconds. Any response code outside of 200 - 299, or any response that takes longer than 15 seconds, will be counted as a failure and retried up to once per hour for 3 days.
• Temperature is always sent in degrees Celsius and relative humidity is sent as a percentage.

Field Descriptions

Root dictionary

apiVersion (integer)

The current version of this spec. The version number will be incremented when any breaking changes are made. The following are considered breaking changes: moving, renaming, or removing a key in the data dictionary; changing a value data type from string to number (integer or decimal) or vice-versa. The following are not considered breaking changes: adding a new key, changing a data type from int to decimal (or vice versa).

eventID (string)

A string that uniquely identifies this specific event. Useful for deduping (in case the endpoint captures the first attempt, but doesn't respond fast enough and we retry).

eventType (string)

This will typically either be "fullsync" or "ping".

isRetransmission (bool)

true/false value that shows if this is not the first attempt to send this event (i.e. if the endpoint did not respond during the first attempt).

data dictionary

macAddress (string)

The MAC address of the data logger.

sessionID (string)

A value that uniquely identifies the logging session the data logger is currently in (defined as starting when a device is activated and ending when the data logger is stopped). Used to combine data sets across multiple events (multiple fullsync events happen per session, and include all data up to the point at which the sync occurred).

eventType (string)

Same as eventType in the root dictionary

eventTime (integer)

Time the event was generated.

activationTime (integer | null)

Time the data logger was programmed. The difference between startLoggingTime and this (i.e. startLoggingTime - activationTime) gives the start delay, if there is one.

startLoggingTime (integer | null)

Time the data logger began logging sensor data.

stopLoggingTime (integer | null)

Time the data logger stopped logging sensor data. This field is null until the logger has been stopped.

latitude and longitude (decimal | null)

Location of the mobile device interacting with the data logger at the time of the sync event. Positive is north and east for latitude and longitude, respectively.

name (string | null)

User-defined name of the this particular logging session.

productNumber (integer | null)

The product number of the Verigo device (Pod, Tag, etc.)

gracePeriod (integer | null)

The amount of time, in seconds, during which a sensor value can exceed thresholds without triggering an alert. If the sensor excursion exceeds this period, an alert is triggered.

loggingInterval (integer | null)

The period, in seconds, at which the data logger captures sensor information. A shorter period will capture information more often, but use more memory.

podVersion (string | null)

The firmware version of the data logger.

batteryLevel (number | null)

Percentage of battery level remaining on the data logger.

sensors: array of dictionaries

sensorType (string)

Human-readable type of the sensor. Possible values: temperature, probe, humidity

highResLoggingTrigger (decimal | null)

For a given sensor, the maximum amount that it can deviate without triggering extra data points to be logged (only applicable if High Resolution Logging is enabled).

currentReading (decimal | null)

The current sensor reading. This field is null if a current reading is not provided in a sync (for example, during the initial sync).

minThreshold (decimal | null)

Minimum sensor threshold. Readings below this value will contribute to triggering of an alert. This field is null if no minimum threshold is specified.

maxThreshold (decimal | null)

Maximum sensor threshold. Readings above this value will contribute to triggering of an alert. This field is null if no maximum threshold is specified.

coefficients (array of integers | null)

Sensor calibration coefficients programmed in the sensor at the time of manufacture.

sensorData (dictionary)

An array of JSON dictionaries that have time and value keys, corresponding to a timestamp and the measurement taken.

deviceEvents (array | null )

Contains a collection of all hardware events logged by the device, if supported, such as Bluetooth connection, button presses, and sensor excursions. T represents the time at which the event occurred (in UNIX/Epoch time) and ID represents the type of event, as indicated by the following table:

Events are logged on devices with a firmware version of at least 1.9 and will be sent to the server using any current version of the mobile app.

Note that event-time pairs are not necessarily unique - for example, if a user presses the button twice within the space of one second, two seemingly identical events may be listed in the log.

Testing

In order to test the webhook simply perform a GET request to https://api.verigo.io/api/v0.6/webhooktest, with a URL-encoded query parameter endpoint set to the URL you want the data posted to. To test Ping functionality, add the type parameter with the value ping.

For example, if you want us to POST a test event to http://google.com/verigo/event, simply GET https://api.verigo.io/api/v0.6/webhooktest?endpoint=http%3A%2F%2Fgoogle.com%2Fverigo%2Fevent

For a Ping event, use https://api.verigo.io/api/v0.6/webhooktest?endpoint=http%3A%2F%2Fgoogle.com%2Fverigo%2Fevent&type=ping