Webhook

Settings for outbound webhooks: configure and test endpoints for shipment and tour events, and set up a warning email when delivery fails.

On the Webhooks tab of the settings, you set up outbound webhooks. With webhooks, X4fleet automatically reports certain events – such as status changes of shipments or tours – to an external system (e.g. an ERP or customer system). As soon as a configured event occurs, X4fleet sends the associated data to the stored address (URL). This tab is intended for administrators who connect X4fleet to third-party systems.

Note: All changes on this tab are applied together with the other settings via the button for saving the settings.

You will find the Webhooks tab within the Settings in the tab bar of the settings page.

Individual options (e.g. the cross-group application) are only visible if you are in the main group.

2. Warning Email When Delivery Fails

So that you do not lose data unnoticed, X4fleet can automatically send a warning email when a webhook delivery fails.

Activate Warning Email

Activate the checkbox «Warning email active».
In the «Warning email» field, enter the recipient address to which the notification should be sent.
Save the settings.

If the delivery of a webhook subsequently fails, the stored address receives a corresponding warning message.

Apply to Subgroups

If you are in the main group, the «Apply to subgroups» option is additionally available. When it is activated, the warning email configuration also applies to the subordinate groups.

Edit the Warning Email Template

You can adjust the content of the warning email in multiple languages. Using the text editor, you edit the template in the available languages. With the editor's insert buttons, you can insert placeholders (variables) into the text, which are automatically replaced by the respective values when sending.

Note: Maintain the template in all required languages so that the recipients receive the warning message in the correct language.

3. Webhook Endpoints for Shipments and Tours

Two separate lists are available on the tab:

Shipment webhooks – endpoints that are triggered by events related to shipments.
Tour webhooks – endpoints that are triggered by events related to tours.

In both lists, you can add, configure, test and remove any number of endpoints.

Add Endpoint

In the desired list (shipments or tours), click the «+» button.
A new, empty row is added to the list.
Configure the row as described in Section 4.
Save the settings.

Remove Endpoint

Using the remove icon of the respective row, you delete an endpoint from the list again. Then save the settings so that the change takes effect.

4. Configuration of an Endpoint

Each webhook endpoint is configured via its own row with the following fields:

Field	Description
Active	Activates or deactivates the endpoint. Only active endpoints are triggered.
Active for subgroups	Applies the endpoint to subordinate groups as well (only visible in the main group).
Pull mode	Switches between push and pull operation. In pull mode, the URL field is hidden, as no active sending to a target address takes place.
URL	The target address to which X4fleet sends the data (only when pull mode is deactivated).
Include shipments	Includes the shipment data in the transmitted payload.
Include transport points	Includes the transport points (pickup/delivery points).
Exclude non-relevant split shipments	Excludes non-relevant partial shipments from splits.
Trigger	Multiple selection of the statuses at which the webhook is triggered (shipment status or tour status).
Content type of the request	Format of the transmitted data (Content-Type of the request).
Encode payload as string	Transmits the payload as an encoded string.
Date/time format	Definition of the format for date and time information in the payload.
Username	Login name for authentication on the target system.
Password	Password for authentication on the target system.
Certificate	Certificate for a secured connection to the target system.

Via the Trigger field, you define at which status changes the endpoint is called. For shipment webhooks, the shipment statuses are available for selection, for tour webhooks the tour statuses.

Note: The URL field is only displayed when pull mode is deactivated. Activate pull mode if the target system retrieves the data itself instead of receiving it from X4fleet.

5. Test Endpoint

Before you use an endpoint in production, you can test it directly from the row.

Configure the row with the desired values (in particular URL and login credentials).
Click the «Test webhook» button of the respective row.
X4fleet sends a test request to the configured address and displays the result.

This way you check whether the target address is reachable and the authentication works correctly, without having to wait for a real event.

6. Saving

All configurations of this tab – the warning email settings as well as the shipment and tour endpoints – are saved together with the other settings. Changes only take effect after saving.

Note: Added or removed endpoints as well as changed field values only apply after the settings have been saved.