Webhooks Documentation

Changes from v1.0

A new device status catch detected for supported devices has been added. The event trap_triggered notifies of triggered traps. Depending on the device status it's possible to check if it's a false alarm. Newer devices which support the new status change their status to either false triggered or catch detected, older devices keep the status triggered.

About

traplinked offers webhooks to be notified instantly about different device related events.

Basic User Flow

Currently webhooks can't be setup using the user interface. Please contact us at api@traplinked.com to exchange all the information needed to register a webhook.

Event types

The following table lists all supported event types together with applicable device types.

Name	Device types	Description
trap_triggered	JERRY, TrapMe	A trap has triggered. Supported devices change their status to `false triggered` or `catch detected`, other devices follow the previous behavior receiving the status `triggered`.
catch_detected	TrapMe	A catch has been detected.
rearmed	JERRY, TrapMe	A trap was rearmed.
offline	JERRY, TOM	A device is offline.
online	JERRY, TOM	A device is back online.
configured	JERRY, TOM	A device was configured.
maintained	JERRY, TOM	A device was maintained.
battery_low	JERRY, TOM, TrapMe	The battery of a device is low.
image_received	TOM	An image was received.

Requests

POST requests are used to transmit data.
The payload is in JSON format.
Responses are expected to be received within a second.
No redirects are allowed.

Request Headers

Arbitrary headers can be set for the webhook. Some headers are reserved, besides that headers can be configured as needed.

Generic Headers

The following standard headers are set:

Name	Description	Value
User-Agent	User agent of the traplinked webhook.	traplinked-webhook/v1.1
Content-Type	Content type of the request.	application/json

traplinked Headers

traplinked specific headers always start with the prefix traplinked-. Currently the following headers exist:

Name	Description
traplinked-Version	The version of the webhook. Example: `v1.1`
traplinked-Request-Timestamp	The timestamp when the request was sent. Example: `2022-01-01T00:00:00`
traplinked-HMAC-SHA256	HMAC-SHA256 in hex format. This header is optional. Example: `12345678`

HMAC

It's recommended to verify the message using a HMAC. The hash algorithm used is SHA-256. Data is sent in hex format. It's necessary to exchange a secret before this feature can be used. To verify the signature the timestamp from the header is needed. The code is computed for the request timestamp appended to the request body.

Example

Using the secret 12345 and the traplinked-Request-Timestamp 2022-01-01T00:00:00 the resulting HMAC-SHA256 is 12345 if the following request body was sent:

{"event":{"type":"trap_triggered","uuid":"080c1300-fbfe-4d11-8b86-bdd4ad2d92b4","timestamp":"2022-01-01T00:00:00","data":{"device":{"serial_number":"TESTDEVICE1","name":"TESTDEVICE1","type":0,"description":"","battery_status":1,"status":3,"last_heartbeat":"2022-01-01T00:00:00","transfer_mode":0,"trap_1":true,"trap_2":false}}}}

Computation is performed on the concatenation of the request body and the request timestamp:

{"event":{"type":"trap_triggered","uuid":"080c1300-fbfe-4d11-8b86-bdd4ad2d92b4","timestamp":"2022-01-01T00:00:00","data":{"device":{"serial_number":"TESTDEVICE1","name":"TESTDEVICE1","type":0,"description":"","battery_status":1,"status":3,"last_heartbeat":"2022-01-01T00:00:00","transfer_mode":0,"trap_1":true,"trap_2":false}}}}2022-01-01T00:00:00

Request Body

The request body is sent in JSON format containing a single event object which contains the following fields:

Name	Description
type	The event type as described in event types. Example: `trap_triggered`
uuid	A unique identifier. Example: `080c1300-fbfe-4d11-8b86-bdd4ad2d92b4`
timestamp	Date and time in UTC the event was triggered. Example: 2022-02-22T20:22:22
data	The payload object. See event data for details.

Event data

The content of the event data depends on the event type and the device type of the event. In this version the data object itself consists of a device object. The device object has the following fields.

Name	Type	Required	Description
name	String	yes	Name of the device.
serial_number	String	yes	Serial number of the device. Example: 1A2B3C4D
type	Integer	yes	The device type. See device type section.
status	Integer	yes	The status of the device. See device status section.
battery_status	Decimal	yes	Battery status of the device. A value between `0.0` and `1.0`.
transfer_mode	Integer	yes	Connection type. See transfer mode section for further details.
operation_mode	Integer	yes	Device operation mode. See operation mode section for further details.
description	String	no	Device description.
last_heartbeat	Datetime	no	Last time the device connected to the server in UTC. Example: `2022-01-01T00:00:00`
latitude	Decimal	no	Latitude of the device.
longitude	Decimal	no	Longitude of the device.
trap_1	Bool	no	Status of trap_1 `true` for triggered, `false` for not triggered
trap_2	Bool	no	Status of trap_2 `true` for triggered, `false` for not triggered
image_timestamp	Datetime	no	Date and time the image was taken in UTC. Example: `2022-01-01T00:00:00`
image_data	String	no	Data URI of the image. Example: `data:image/jpeg;base64,...`

Device Type

Type	Description
0	JERRY
1	JERRY LoRa
2	TrapMe
3	TOM

Device Status

Status	Description
0	Device is inactive.
1	Device is active.
2	Heartbeat failed
3	Device has been triggered.
4	Battery is low.
5	Location mode is active.
6	Unstable Wi-Fi connection
7	Light infestation
8	Severe infestation
9	False triggered
10	Activity warning
11	Activity critical
12	Catch detected

Transfer Mode

Mode	Description
0	Wi-Fi
1	LoRa
2	NB-IoT

Operation Modes

Mode	Description
0	Snaptrap mode
1	Movement mode
2	Insect mode

Example

{
    "event": {
        "type": "trap_triggered",
        "uuid": "080c1300-fbfe-4d11-8b86-bdd4ad2d92b4",
        "timestamp": "2022-01-01T00:00:00",
        "data": {
            "device": {
                "serial_number": "TESTDEVICE1",
                "name": "TESTDEVICE1",
                "type": 0,
                "description": "",
                "battery_status": 1,
                "status": 3,
                "last_heartbeat": "2022-01-01T00:00:00",
                "transfer_mode": 0,
                "trap_1": true,
                "trap_2": false
            }
        }
    }
}

Response

A successful response returns a response code between 200 and 299. In case of an error the request is queued. The client will retry the request after one minute for a maximum of 5 times.