Bumblebee docs

Webhooks

Bumblebee has the ability to send an HTTP POST request every time new data is received from a node.

This functionality is called a 'webhook'. After setting up a webhook, Bumblebee will send new data to the configured URL so you immediately know when for example the location of one of your assets has changed.

Webhooks can be configured by administrators here.

Creating a webhook

For the webhook you have the following options:

URL This is the endpoint to send the HTTP POST request to.
Data Select which data updates you want to receive.
Headers You can add multiple key / value pairs which will be sent as HTTP headers with every request. If your request required HTTP authorization for example, you can add an Authorize header with your credentials.

You can request updates for the following data:

Battery levels Receive a request every time we receive a battery level from a node.
GPS-locations Receive a request every time we receive a GPS-location from a node.
Temperatures Receive a request every time we receive temperature from a node.
Sensor values Receive a request every time we receive sensor values from a node.
Sigfox messages Receive a request every time we receive any data from a node.

Receiving a webhook

To receive a webhook message, your webserver must accept an HTTP POST request on the configured URL. All request always contain a JSON body containing the data you subscribed for.

HTTP method
POST
Headers
Content-Type Always application/json to indicate Bumblebee is sending JSON data.
User-Agent Contains the version of Bumblebee that sent the request.
(E.g. Bumblebee v1.0.1 webhooks)
X-Request-ID Contains the ID of the webhook message, you can persist this ID to check if you already processed the webhook.
Custom headers The headers configured in the webhook will also be sent.
Body
{
  "data_type": "Type",
  "data": {
    "id": "Abc123",
    "latitude": 52.255223,
    "longitude": 6.160636,
    "radius_accuracy": 48.5,
    "recorded_at": "2024-01-01T13:00:00.000+01:00"
  },
  "asset": {
    "id": "Abc123"
  },
  "node": {
    "id": "Ref001",
    "sigfox_id": "123ABC"
  },
  "message_info": {
    "id": "Abc123",
    "sent_at": "2024-01-01T13:00:00.000+01:00",
    "message_number": 123,
    "external_io": 1,
    "day_number": 123
  }
}
data_type Contains the type of data that is being sent. See data for more information.
data Contains the actual data of the request. The contents of this node differ based on the value of data_type. See data for more information.
asset Contains the ID of the asset related to the data. This node is omitted if the asset is unknown.
node Contains the ID and Sigfox ID of the node that sent the data. This node is omitted if the node is unknown.
message_info Contains metadata from the Sigfox message that contained this data. This node is omitted for battery levels and Sigfox messages. If present it contains the ID of the message info, the timestamp when the message was sent, the sequence number for the message, and the state of the external i/o. See the Sigfox message info section for more information.

Response

Status 2XX

When the webhook recipient responds with a 2XX HTTP status, the webhook message will be marked as delivered.

Status 4XX

When the webhook recipient responds with a 4XX HTTP status, the webhook message will be marked as canceled and will not be tried again.

Status 5XX

When the webhook fails or the recipient responds with a 5XX HTTP status, the webhook message will be marked as failed and will be retried for a maximum of 5 times. If all 6 attempts fail, the webhook message will be marked as canceled and will not be tried again.

Error message

The recipient can respond with an optional error message which will be persisted in Bumblebee. To respond with an error message, add a Content-Type header with application/json as the value, and add a JSON object to the body containing an error node: 

{"error": "Your error message"}

Error messages will only be saved when the recipient responds with a 4XX or 5XX status, and will be truncated to 750 characters.

Retries

When a webhook fails or the recipient responds with a 5XX HTTP status, the delivery of the webhook message will be retried after a staggered delay. The timing of this is as follows:

Attempt Delay
1 None. The first attempt will be done immediately.
2 After 1 minute.
3 After 5 minutes.
4 After 15 minutes.
5 After 1 hour.
6 After 3 hours.

Data

The data sent by Bumblebee differs for each data type. See the documentation below for the exact contents of each request, plus documentation for the information in the data node.

Battery level

Data type
battery_level/update
Body
{
  "data_type": "battery_level/update",
  "data": {
    "recorded_at": "2024-01-01T13:00:00.000+01:00",
    "percentage": 90
  },
  "asset": {
    "id": "Abc123"
  },
  "node": {
    "id": "Ref001",
    "sigfox_id": "123ABC"
  }
}
recorded_at When the battery level was recorded.
percentage Contains the charge-percentage of the battery, rounded to 5 percent.

GPS-location

Data type
geo_location/create
Body
{
  "data_type": "geo_location/create",
  "data": {
    "id": "Abc123",
    "latitude": 52.255223,
    "longitude": 6.160636,
    "radius_accuracy": 48.5,
    "recorded_at": "2024-01-01T13:00:00.000+01:00"
  },
  "asset": {
    "id": "Abc123"
  },
  "node": {
    "id": "Ref001",
    "sigfox_id": "123ABC"
  },
  "message_info": {
    "id": "Abc123",
    "sent_at": "2024-01-01T13:00:00.000+01:00",
    "message_number": 123,
    "external_io": 1,
    "day_number": 123
  }
}
latitude The latitude of the GPS-coordinate, between -90 and 90
longitude The longitude of the GPS-coordinate, between -180 and 180
radius_accuracy The accuracy of the GPS-coordinate. This feature is unimplemented for now.
recorded_at When the GPS-coordinate was recorded.

Temperature

Data type
temperature/create
Body
{
  "data_type": "temperature/create",
  "data": {
    "id": "Abc123",
    "degrees": 21.5,
    "recorded_at": "2024-01-01T13:00:00.000+01:00"
  },
  "asset": {
    "id": "Abc123"
  },
  "node": {
    "id": "Ref001",
    "sigfox_id": "123ABC"
  },
  "message_info": {
    "id": "Abc123",
    "sent_at": "2024-01-01T13:00:00.000+01:00",
    "message_number": 123,
    "external_io": 1,
    "day_number": 123
  }
}
degrees The temperature of the node in degrees Celcius.
recorded_at When the temperature was recorded.

Sensor values

Data type
sensor_value/create
Body
{
  "data_type": "sensor_value/create",
  "data": {
    "id": "Abc123",
    "recorded_at": "2024-01-01T13:00:00.000+01:00",
    "sensor1_raw_value": 123,
    "sensor2_raw_value": 456,
    "sensor3_raw_value": 789
  },
  "asset": {
    "id": "Abc123"
  },
  "node": {
    "id": "Ref001",
    "sigfox_id": "123ABC"
  },
  "message_info": {
    "id": "Abc123",
    "sent_at": "2024-01-01T13:00:00.000+01:00",
    "message_number": 123,
    "external_io": 1,
    "day_number": 123
  }
}
sensor1_raw_value The raw value of sensor 1 ranging from 0 to 4095.
sensor2_raw_value The raw value of sensor2 ranging from 0 to 4095.
sensor3_raw_value The raw value of sensor3 ranging from 0 to 4095.
recorded_at When the sensor value was recorded.

Sigfox message info

Data type
sigfox_message_info/create
Body
{
  "data_type": "sigfox_message_info/create",
  "data": {
    "id": "Abc123",
    "sent_at": "2024-01-01T13:00:00.000+01:00",
    "created_at": "2024-01-01T13:00:00.000+01:00",
    "recorded_at": "2024-01-01T13:00:00.000+01:00",
    "snr": 1.234,
    "rssi": 1.234,
    "sequence": 123,
    "message_number": 123,
    "external_io": 1,
    "day_number": 123,
    "processing_error": "Processing Error",
    "node_configuration": {
      "id": "Ref001",
      "name": "Name",
      "behavior_id": "Abc123",
      "behavior_version": 3,
      "behavior_profile": "unless",
      "trigger_type": "motion"
    }
  },
  "asset": {
    "id": "Abc123"
  },
  "node": {
    "id": "Ref001",
    "sigfox_id": "123ABC"
  }
}
recorded_at When the data was recorded by the node. This field can be null for acknowledgement messages or if the data could not be parsed.
sent_at When the message was sent by the node.
(Please note: If a message is being sent again, the sent_at will contain the timestamp for when the message was sent again, not the original timestamp)
snr The signal-to-noise ratio in dB.
rssi The received signal strength indicator in dBm.
sequence The Sigfox sequence number of the message.
message_number The Bumblebee sequence number of the message. This field can be null for acknowledgement messages or if the data could not be parsed.
external_io The state of the external i/o at the time of the message. A value of 0 means the external i/o is active, a value of 1 means the external i/o is inactive. This value will be nil for acknowledgement messages, if the data could not be parsed, or if the node version is below 0.9
created_at When we received this message from Sigfox.
processing_error Errors occured during the processing of the message. Omitted when empty.
node_configuration The node-configuration that was active at the time the message was recorded.
This can differ from the configuration that is assigned to the asset if the node has not received the latest configuration changes yet. This node can be null for acknowledgement messages or if the data could not be parsed.
node_configuration/id The id of the configuration.
node_configuration/name The name of the configuration.
node_configuration/behavior_id The ID of the behavior that was active.
node_configuration/behavior_version The version of the behavior that was active. The version will change every time you alter the behavior.
node_configuration/behavior_profile The profile of the behavior that was active, the value is one of: default or unless.
node_configuration/trigger_type The type of trigger that caused this message to be sent, only present if behavior_profile is unless.

Message log

All webhook messages sent by Bumblebee are accessible by administrators through the backoffice via your webhook. The webhooks for your customer are listed here. After opening one of your webhooks you can access the message log from the sidebar on the left.

By default, all messages are listed ordered by descending creation date/time. Optionally you can filter the messages by their state: pending, sent, failed, or canceled.

States
pending The message has been created but has not been sent yet.
failed Delivery of the message has failed so far, Bumblebee will retry delivering the message.
canceled Delivery of the message has failed, Bumblebee will not retry delivering this message.
sent The message has been successfully delivered.
Status message

If the message status is failed or canceled, Bumblebee will tell you why the delivery failed if you open the message.