Outgoing Webhooks

Outgoing Webhooks allow you to connect data and events coming from Datacake to other systems.

What are webhooks

A webhook pushes real-time notifications from Datacake to your app. Datacake uses HTTPS to send these notifications to your app as a JSON payload. You can then use these notifications to execute actions in your backend systems.

Use cases

Sync device measurements to your system

You can create a webhook that listens to "measurement recorded" events and stores them in your external database.

Act on raw data from payload decoders

Sometimes, payload decoders return more data than is stored in the time-series database. You can use webhooks to trigger actions based on this information, without paying for storage.

Get started

You can find the Webhooks settings in the "Integrations" section.

Get started by clicking the "Add Webhook" button. You will be presented with a form that asks for the following information:

  • Endpoint URL -> The URL that receives the events. One good service for testing is https://webhook.site/

  • Description -> An optional description

  • Events to send -> You can choose which events should trigger the webhook

Enter your data and click "Create Webhook". Your endpoint should now start receiving data.

Events

In the settings of your outgoing webhook, you can define one or more events that will trigger the webhook and forward data. Learn more about what the differences are and why you want to use them.

Decoder output

This is the raw output from a device payload decoder as can also be seen in a device debug view, including:

  • Decoder returned data

  • Console Log

  • Device Information (LoRaWAN or Particle device types)

An example output looks like the following:

{
  "data": {
    "log": null,
    "device": null,
    "result": [
      {
        "field": "TOWER_LOCATION",
        "value": "(34.492523,136.171631)",
        "device": "dev:864475044240892"
      },
      {
        "field": "DEVICE_LOCATION",
        "value": "(34.4823475,136.16275390624997)",
        "device": "dev:864475044240892"
      },
      {
        "field": "RSSI",
        "device": "dev:864475044240892"
      },
      {
        "field": "BARS",
        "device": "dev:864475044240892"
      },
      {
        "field": "VOLTAGE",
        "device": "dev:864475044240892"
      },
      {
        "field": "CARD_TEMPERATURE",
        "device": "dev:864475044240892"
      },
      {
        "field": "ORIENTATION",
        "device": "dev:864475044240892"
      },
      {
        "field": "PM1",
        "value": 3.4,
        "device": "dev:864475044240892"
      },
      {
        "field": "PM25",
        "value": 4.88,
        "device": "dev:864475044240892"
      },
      {
        "field": "PM10",
        "value": 4.88,
        "device": "dev:864475044240892"
      },
      {
        "field": "TEMPERATURE",
        "value": 10.616931,
        "device": "dev:864475044240892"
      },
      {
        "field": "PRESSURE",
        "value": 95909.72,
        "device": "dev:864475044240892"
      },
      {
        "field": "HUMIDITY",
        "value": 59.889774,
        "device": "dev:864475044240892"
      }
    ],
    "product": "ef6275c7-3e9b-4134-9bef-24bc276a9592",
    "execution_time": 664535
  },
  "event": "decoder_output"
}

Advanced usage

Usually, decoders on Datacake return an array of dictionaries where each dictionary holds the measurement information, device serial (not on LoRaWAN and Particle devices), and the field identifier.

However, as the outgoing webhook does transport any information coming from a decoder you could also include additional information here that is not readable for the Datacake backend but can be used by your systems.

Device measurements

This event type is triggered only on new measurement values recorded on the database. This does not necessarily contain all the data of all fields on a device as it only holds the fields that are being inserted on the last message received by your device.

So if your device does receive a single field message per MQTT for example, this only contains the latest field data.

The webhook data would look like the following:

{
  "data": [
    {
      "field": "TOWER_LOCATION",
      "value": "(26.2319375,-81.742609375)",
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852979
    },
    {
      "field": "DEVICE_LOCATION",
      "value": "(26.237302500000006,-81.74094921875)",
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852979
    },
    {
      "field": "ORIENTATION",
      "value": "",
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852980
    },
    {
      "field": "PM1",
      "value": 0.14084508,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852980
    },
    {
      "field": "PM10",
      "value": 0.8309859,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852981
    },
    {
      "field": "TEMPERATURE",
      "value": 19.141228,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852981
    },
    {
      "field": "PRESSURE",
      "value": 102081.35,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852981
    },
    {
      "field": "HUMIDITY",
      "value": 66.95572,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852981
    },
    {
      "field": "PM25",
      "value": 0.28169015,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852980
    },
    {
      "field": "TOWER_LOCATION",
      "value": "(26.2319375,-81.742609375)",
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852984
    },
    {
      "field": "DEVICE_LOCATION",
      "value": "(26.237302500000006,-81.74094921875)",
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852984
    },
    {
      "field": "ORIENTATION",
      "value": "",
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852986
    },
    {
      "field": "PM25",
      "value": 0.16901408,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852986
    },
    {
      "field": "PM10",
      "value": 0.5492958,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852986
    },
    {
      "field": "TEMPERATURE",
      "value": 19.0143,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852986
    },
    {
      "field": "PRESSURE",
      "value": 102088.086,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852986
    },
    {
      "field": "HUMIDITY",
      "value": 66.58315,
      "device": "f7384fd1-9e7f-4540-b4ed-5fa5810bcc27",
      "timestamp": 1647852987
    }
  ],
  "event": "device_measurement"
}

This event is triggered whenever a downlink is sent to a LoRaWAN or MQTT device. It will trigger both on manual and automatic (via rules) downlinks. The structure is as follows:

{
  "data": {
    "meta": {
      "type": "lorawan",
      "fport": 1,
      "downlink": "a6895656-8198-41fe-9c0e-f49074311190"
    },
    "device": "a52e6324-2cf9-4534-b523-819d94299414",
    "payload": "AQI=",
    "product_id": "4e8e8623-18c4-4798-9877-699058a00e24",
    "product_slug": "temperatur-dach"
  },
  "event": "downlink"
}

Troubleshooting

The list of webhooks contains useful debugging information, such as a chart of the number of requests in the last seven days and the error rate.

Click on one of your webhooks to see a list of the last requests as well as the response from your server.

Last updated