Webhooks Documentation
Changes from v1.3
- New device type: JERRY Bait Rat
- New operation mode: Bait
- New event types: activity_noticed, activity_threshold_reached, bait_low, activity_threshold_reached_and_bait_low
- New bait monitoring fields for JERRY Bait Rat devices
- New device statuses: "Bait low", "Activity critical and bait low".
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, Trapsensor, JERRY LoRa | A catch has been detected. |
| rearmed | JERRY, JERRY LoRa, JERRY Bait Rat, TrapMe, Trapsensor | A trap was rearmed / Bait has been replaced |
| offline | JERRY, JERRY LoRa, JERRY Bait Rat, TOM, Trapsensor | A device is offline. |
| online | JERRY, JERRY LoRa, JERRY Bait Rat, TOM, Trapsensor | A device is back online. |
| configured | JERRY, TOM | A device was configured. |
| maintained | JERRY, TOM | A device was maintained. |
| battery_low | JERRY, JERRY LoRa, JERRY Bait Rat, TOM, TrapMe, Trapsensor | The battery of a device is low. |
| image_received | TOM | An image was received. |
| false_triggering | JERRY LoRa, TOM, Trapsensor | False triggering event. |
| activity_noticed | JERRY Bait Rat | Activity was noticed on the bait pad. |
| activity_threshold_reached | JERRY Bait Rat | Activity threshold has been reached. |
| bait_low | JERRY Bait Rat | Bait level is low. |
| activity_threshold_reached_and_bait_low | JERRY Bait Rat | Activity threshold reached and bait is low. |
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.4 |
| 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.4 |
| 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_1true for triggered, false for not triggered. null for JERRY Bait Rat devices. |
| trap_2 | Bool | no | Status of trap_2true for triggered, false for not triggered. null for JERRY Bait Rat devices. |
| 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,... |
| is_bait_monitoring_enabled | Bool | no | Whether bait monitoring is enabled. Only available for JERRY Bait Rat devices, null for other device types. |
| bait_low_count | Integer | no | Bait low count. Only available for JERRY Bait Rat devices, null for other device types. |
| bait_pad_activity_count | Integer | no | Bait pad activity count. Only available for JERRY Bait Rat devices, null for other device types. |
| activity_alert_threshold | Object | no | Activity alert threshold. See activity alert threshold section for further details. Only available for JERRY Bait Rat devices, null for other device types. |
| bait_manufacturer_and_type | String | no | Bait manufacturer and type. Only available for JERRY Bait Rat devices, null for other device types. |
| bait_weight_grams | Integer | no | Bait weight in grams. Only available for JERRY Bait Rat devices, null for other device types. |
| bait_calibration_weight_grams | Integer | no | Remaining bait weight (threshold) calibration in grams. Only available for JERRY Bait Rat devices, null for other device types. |
| last_bait_replaced_at | Datetime | no | Last time bait was replaced in UTC. Example: 2022-01-01T00:00:00. Only available for JERRY Bait Rat devices, null for other device types. |
| last_bait_replaced_by_name | String | no | Name of user who last replaced bait. Only available for JERRY Bait Rat devices, null for other device types. |
| last_activity_reset_at | Datetime | no | Last time activity was reset in UTC. Example: 2022-01-01T00:00:00. Only available for JERRY Bait Rat devices, null for other device types. |
| last_activity_reset_by_name | String | no | Name of user who last reset activity. Only available for JERRY Bait Rat devices, null for other device types. |
| is_bait_available | Bool | no | Whether bait is available. Only available for JERRY Bait Rat devices, null for other device types. |
Device Type
| Type | Description |
|---|---|
| 0 | JERRY |
| 1 | JERRY LoRa |
| 2 | TrapMe |
| 3 | TOM |
| 4 | Trapsensor |
| 5 | JERRY Bait Rat |
Device Status
| Status | Description |
|---|---|
| 0 | Device is inactive. |
| 1 | Device is active / Bait is available (JERRY Bait Rat) |
| 2 | Heartbeat failed |
| 3 | Device has been triggered. |
| 4 | Battery is low. |
| 6 | Unstable Wi-Fi connection |
| 7 | Light infestation |
| 8 | Severe infestation |
| 9 | False triggered |
| 10 | Activity warning |
| 11 | Activity critical |
| 12 | Catch detected |
| 13 | Bait low |
| 14 | Activity critical and bait low |
For JERRY Bait Rat devices, "Activity critical" (status 11) and "Activity critical and bait low" (status 14) indicate that the configured activity threshold has been reached. The activity threshold defines the number of activity events within a specific timeframe (see activity alert threshold) that triggers the status change.
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 |
| 3 | Bait mode |
Activity Alert Threshold
The activity alert threshold is an object with the following fields. This field is only available for JERRY Bait Rat devices and null for other device types.
| Name | Type | Description |
|---|---|---|
| threshold_value | Integer | Activity threshold. When the number of activities exceeds this value within the specified timeframe, the device receives status 11 and report type 22 is sent |
| timeframe_value | Integer | Number of days or hours during which activities are counted toward the threshold |
| timeframe_type | String | Unit of the timeframe. Possible values: "d" (days), "h" (hours) |
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,
"is_bait_monitoring_enabled": null,
"bait_low_count": null,
"bait_pad_activity_count": null,
"activity_alert_threshold": null,
"bait_manufacturer_and_type": null,
"bait_weight_grams": null,
"bait_calibration_weight_grams": null,
"last_bait_replaced_at": null,
"last_bait_replaced_by_name": null,
"last_activity_reset_at": null,
"last_activity_reset_by_name": null,
"is_bait_available": null
}
}
}
}
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.