Webhooks

The primary method that Anisca Bird uses to deliver data is through the use of webhooks. A webhook URL will be called via a POST request with the message encoded as a JSON body.

Messages

Your webhook URL should be prepared to receive the following messages:

weight: Bird detected and weighed

This message is sent when a ringed bird is detected on the perch. A detection is valid if the RFID tag was successful read.

POST example.com/webhook

Example request body:

{
    "timestamp": 1648642396,
    "serial": "CODEABFFEE",
    "device_id": "secret-red-wake",
    "type": "weight",

    "activation": {

        "latlng": "46.535,6.569",
        "site_id": "rdc20",
        "activation_date": 1648641394
    },

    "body": {

        "duration": 12,
        "flags":"ab",
        "weight": 120.5,
        "uid": "0600c9a463",
        "raw_adc_pos": 56020,
        "stddev": 1,
        "temperature": -10
    }
}

Request JSON Object

• timestamp (integer) – Epoch timestamp (UTC+0): seconds since January 1, 1970 12:00:00 AM

• serial (string) – device serial number

• device_id (string) – human readable hash of serial number that is also printed on device label

• type (string) – message type (one of weight, status, offset, or calibration)

• activation (string) – when and where this device was last activated

• duration (integer) – number of seconds that owl is on perch (max. 240)

• flags (integer) – reserved

• weight (integer) – weight estimate in 0.01 grams (unsigned value)

• uid (integer) – RFID UID (hexadecimal). Attention: the second byte of the RFID tag is not transmitted in order to save data. Example: The UID 050031b049 will become 0531b049.

• raw_adc_pos (integer) – raw ADC value from “positive excitation” (incl. offset)

• stddev (integer) – weight measurement series standard deviation in 0.1 grams

• temperature (integer) – temperature in degrees Celsius (signed value)

status: Device status

Device status is sent twice a day.

POST example.com/webhook

Example request body:

{
    "timestamp": 1648642396,
    "serial": "CODEABFFEE",
    "device_id": "secret-red-wake",
    "type": "status",

    "activation": {

        "latlng": "46.535,6.569",
        "site_id": "rdc20",
        "activation_date": 1648641394
    },

    "body": {

        "header": "ff",
        "events_with_id": 29,
        "events_unknown_id": 16,
        "flags": "ab",
        "vbat_mv": 4620,
        "memory_used": 56,
        "days_since_boot": 120
    }
}

Request JSON Object

• timestamp (integer) – Epoch timestamp (UTC+0): seconds since January 1, 1970 12:00:00 AM

• serial (string) – device serial number

• device_id (string) – human readable hash of serial number that is also printed on device label

• type (string) – message type (one of weight, status, offset, or calibration)

• activation (string) – when and where this device was last activated

• header (integer) – internal device status header (0xFF)

• events_with_id (integer) – number of events with successful RFID detection since last status update [0-255]. The value of 255 means >=255.

• events_unknown_id (integer) – number of events with UN-successful RFID detection since last status update [0-255]. The value of 255 means >=255.

• flags (integer) – reserved

• vbat_mv (integer) – Battery voltage in mV

• memory_used (integer) – Percentage of Flash memory used [0-100]

• days_since_boot (integer) – Number of days since last reboot [0-255]. The value of 255 means >=255.

offset: Tare weight

This is the tare weight (unladen weight) and is sent every 2 hours.

POST example.com/webhook

Example request body:

{
    "timestamp": 1648642396,
    "serial": "CODEABFFEE",
    "device_id": "secret-red-wake",
    "type": "offset",

    "activation": {

        "latlng": "46.535,6.569",
        "site_id": "rdc20",
        "activation_date": 1648641376
    },

    "body": {

        "header": "fa",
        "flags": "ac",
        "weight": 31660,
        "raw_adc_pos": 4999,
        "raw_adc_neg": 4986,
        "stddev": 0,
        "temperature": 20
    }
}

Request JSON Object

• timestamp (integer) – Epoch timestamp (UTC+0): seconds since January 1, 1970 12:00:00 AM

• serial (string) – device serial number

• device_id (string) – human readable hash of serial number that is also printed on device label

• type (string) – message type (one of weight, status, offset, or calibration)

• activation (string) – when and where this device was last activated

• header (integer) – internal device status header (0xFA)

• flags (integer) – reserved

• raw_adc_pos (integer) – raw tare ADC value from “positive excitation”

• raw_adc_neg (integer) – raw tare ADC value from “negative excitation”

• stddev (integer) – tare measurement series standard deviation in 0.1 grams

• temperature (integer) – temperature in degrees Celsius (signed value)

calibration: Calibration result

This message is sent after the user has performed a calibration.

POST example.com/webhook

Example request body:

{
    "timestamp": 1648642396,
    "serial": "CODEABFFEE",
    "device_id": "secret-red-wake",
    "type": "calibration",

    "activation": {

        "latlng": "46.535,6.569",
        "site_id": "rdc20",
        "activation_date": 1648641376
    },

    "body": {

        "slope": 29,
        "intercept": 25,
        "temperature": 2,
        "r2": 1.0
    }
}

Request JSON Object

• timestamp (integer) – Epoch timestamp (UTC+0): seconds since January 1, 1970 12:00:00 AM

• serial (string) – device serial number

• device_id (string) – human readable hash of serial number that is also printed on device label

• type (string) – message type (one of weight, status, offset, or calibration)

• activation (string) – when and where this device was last activated

• slope (integer) – linear regression slope: (raw ADC counts per 10mg)

• intercept (integer) – linear regression intercept: (raw ADC value)

• r2 (float) – linear regression R^2

• temperature (integer) – temperature in degrees Celsius (signed value)