Webhooks — actions triggered by specific events

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

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. 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.

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.property.x — refers to a specific user property, where "x" is the property name.

      Note: If you need a “%” symbol in the generated text, just use %% notation without the expression.

      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

Webhooks API

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

Troubleshooting

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

flespi webhooks logs