Webhooks — actions triggered by specific events

Catch events generated in your account and execute internal or external HTTP calls.

Essentials

Webhooks are used to catch events generated in the MQTT bus of your account and execute HTTP calls to some endpoint per each received and validated MQTT message.

Here are a few cases of how webhooks can be used:

  • If the vehicle exits the allowed geofence, send an email notifying the operator (requires a third-party service). 
  • If the device disconnects from flespi, add a record about that into this device messages (internal call to the flespi platform).

How webhooks work

There are triggers, filters, and actions.

The trigger for the webhook is an MQTT message received by the flespi MQTT broker. In flespi all user-initiated and system actions generate specific MQTT events in corresponding topics. You can find a list of the most important MQTT topics in the MQTT Topics Directory section of the flespi panel, or in this MQTT topics guide. Some topics most commonly used as triggers are listed below. You can have up to 3 triggers for the webhook. If several triggers are specified, they will be joined using OR logic.

The filter lets you narrow down the trigger by specifying the specific values for topics, content, and other message fields.

The action is an HTTP request, either internal — to perform something inside flespi itself (post a message, create a device, assign a plugin, etc.) or external — to execute something on a third-party service (send email or SMS, generate a report, etc.).

 Before execution, the HTTP request can be flexibly configured, including URI, headers, and request body.

Webhooks are executed in a first-in-first-out order.

Several webhooks can be grouped under a common name. In this case, the event delivery is carried out to one of them selected randomly.

Common trigger topics

Below is a list of some (not all) MQTT topics that are commonly used as triggers in the webhook configuration:

TopicMeaning
flespi/message/gw/devices/+new message from device ("+" means any item, you can specify the item ID to be more specific)
flespi/state/gw/devices/+/connecteddevice went online
flespi/state/gw/channels/+/idents/+device connected to channel
flespi/interval/gw/calcs/+/devices/+/activatedcalculator interval activated
flespi/interval/gw/calcs/+/devices/+/deactivatedcalculator interval deactivated


How to create a webhook?

  1. Log in to the flespi panel
  2. Navigate to Webhooks in the left-side menu and click the "+" button in the bottom right corner to add a new webhook:
    create new webhook flespi
  3. You will be offered to use a template to create your webhook, so if you want to create it from scratch, just close this dialog:
    flespi webhooks templates dialog
  4. Configure the webhook by specifying the trigger(s), filters (if needed), and the HTTP call details:
    flespi webhook configuration
    The URL, BODY, and HEADERS fields contain static text with the injected values from the message. The injected values must be enclosed in the % and % marks:
    • timestamp — timestamp of the message, e.g. 1680680536.527043: 

    • cid — account ID the message appeared on, e.g. 123;

    • token_id — token ID from which this message was published (N/A for MQTT messages generated by flespi itself);

    • topic — exact text of topic messages was posted to, e.g. flespi/state/gw/devices/123/connected;

    • topics[x] — array of words, e.g. [flespi, state, gw, devices, 123, connected]. Zero-based index, to access device-id use topics[4] in the expression;

    • payload — message payload data (text);

    • payload[x] — in case payload is a JSON object, you can access sub-fields as payload[“device_id”] and so on.

    • user_properties.x — refers to a specific user property, where "x" is the property name.

    • responses[0..x] — access to the response of chained request, where x is the zero-based index of the chain.

    • response_codes[0..x] — array with received response codes

      Note: If you need a “%” symbol in the generated text, just use %% notation without the expression.
      Note: If you need to use "%" symbol inside expression use %{expression}% notation, e.g. %{strftime(timestamp, "%h:%m:%s")}%

      You can use rich expressions syntax to preprocess the fields values.

  5. Click Save to create the webhook.

How to disable a webhook?

Once you click Save to create a webhook, it is automatically enabled. To disable it, uncheck the "Enabled" property in the webhook configuration and click Save or click the "Disable" button on the interface:

flespi webhook disable

Chained requests

Webhook supports up to 5 sequential HTTP requests. Responses received for the previous requests are available for the subsequent requests in responses[0..x] array. 

flespi webhook chained request

Webhooks provide two ways to validate requests. The first allows validation before the request is sent, and the second is applied after the response is received. Both validators could be applied together. If validation fails, it is possible to select what to do:

  • Do not deliver message
  • Invoke the next request in the chain
  • Retry message delivery

flespi webhook validation

Webhooks API

To perform any operations with the webhooks, use the webhooks API.

Troubleshooting

You can find all log records related to the webhook in the Logs tab on the webhook screen:

flespi webhooks logs

The log message consists of these important fields:

  • message - MQTT message that triggered webhook with information about its topic, payload, user_properties, etc;
  • request_uri - URI where webhook request was sent;
  • request_headers - HTTP headers that were used during webhook request;
  • request_body - HTTP body that was used during webhook request;
  • response_code - HTTP response code that was returned in response to a webhook request;
  • response - HTTP body that was returned in response to a webhook request;
  • reason - additional diagnostic information and the reason of webhook processing failure;

Each such field represents a JSON array.  Each element in the array represents an input or output data of a HTTP request that was triggered for each request in the chain. You can check these fields to understand which MQTT message triggered the webhook and how it formatted the URL, headers and body for each request. In case of any failure especially related with expressions-based templating take attention to a reason field which will contain information on what field has failed to format and what was the error.

For detailed troubleshooting the raw traffic generated by the webhook is available under Traffic button. 

flespi webhooks logs

There you may see exact bytes of HTTP request sent by the webhook and the response replied by the server.

flespi webhooks logs


See also
Apply webhooks to events from calculators to invoke your lambda upon an aggregated event happened to the device
Five ways for the massive creation of devices in the flespi platform.