Webhooks — actions triggered by specific events

• Essentials
• How webhooks work
• Common trigger topics
• How to create a webhook?
• How to disable a webhook?
• Chained requests
• Webhooks API
• Troubleshooting

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:

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:
   
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:
   
4. Configure the webhook by specifying the trigger(s), filters (if needed), and the HTTP call details:
   
   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.
     
     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:

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. 

Also, request has a validation with several rules. 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

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: