Webhooks allow you to listen for events in Fleetio.
You can add a webhook, and subscribe it to one of our Webhook Events. Fleetio will then send an HTTP
POST request to your server whenever that event occurs. The request body will contain related data.
Webhooks are available through our Advanced Plan
You can configure webhook endpoints under account settings. If your endpoint requires authentication, you can provide an Authorization value when setting up your webhook. This value gets passed through as the HTTP Authorization header when Fleetio makes a POST call to your webhook endpoint. All credentials are securely stored and encrypted in Fleetio.
POST request to your endpoint will have a
Content-Type header of
The request body will contain a JSON message that looks like the following:
. . .
|The object which triggered the webhook.||Example: |
|ISO8601 string that reflects either the account's time zone, or Central Time if there is none set.||Indicates when the event occurred.|
|The User that triggered the event, or ||Example: A User creates an Issue. This attribute will be set to that User.|
* In some cases, the
triggered_by attribute could be
null, ie. Fleetio may generate an event as part of a background job without User involvement.
Timing & Delivery
Webhook Events are asynchronous. Please do not rely on them for anything time sensitive. We will do our best to deliver them to your endpoint as soon as possible.
Your application should be prepared for delays in receiving messages, or even receiving messages out of order if there are interruptions or delays in the network.
Please contact firstname.lastname@example.org if you experience delays longer than 1 hour.
Whenever an update event occurs in Fleetio, Fleetio will wait a little for any other identical events before firing off a message to your webhook. For example, if five users edited the same Vehicle within a single minute, Fleetio will only deliver one webhook message. We debounce messages like this to avoid overloading your server.
Events based on creation or deletion are fired off as soon as possible.
Fleetio signs each message to protect your data from tampering. Each webhook you've added has its own shared key.
You can find the shared key by visiting Webhooks settings, and selecting "View Secret" from the dropdown menu of a webhook:
Using this key, Fleetio computes the HMAC SHA-256 digest with the message body and sends it in the
X-Fleetio-Webhook-Signature HTTP header.
To verify that incoming messages came from Fleetio, you should take the following steps:
- Compute the HMAC SHA-256 digest of the raw HTTP body using the Webhook Secret Key.
- Compare the computed digest with the
In Ruby, it would look like this:
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), webhook.shared_key, message.body)
Responding to Messages
Your endpoint MUST respond with an HTTP
200 code within 30 seconds. Any other code will make Fleetio think your endpoint failed to handle the message.
Failures and Retries
If you fail to handle the message, Fleetio will try 5 times over the next hour to deliver the message to your endpoint. If none of those succeed, Fleetio will try once per hour for the next 24 hours.
|1||1 minute after the original event|
|2||1 minute after last failure|
|3||5 minutes after last failure|
|4||15 minutes after last failure|
|5||30 minutes after last failure|
|6 – 29||hourly for the next 24 hours|
If your endpoint fails to successfully handle the message by the end of the 24 hour period, we will mark the message as failed and undeliverable. The account owner and the creator of the webhook will also receive an email notification.
After 3 consecutive failed messages, we will disable your webhook, and send an email notification to the account owner and the webhook creator. It is up to you to fix your endpoint and then manually re-enable the webhook under your Fleetio account settings.
Viewing Webhook Events
You can view a list showing the status and timing of recent delivery attempts by navigating to the Webhooks section of the Fleetio Account Settings.
Fleetio will keep record of webhook events for 30 days after an event occurred.
Webhook Event Statuses
|Success||Message delivery succeeded .|
|Failed||Message delivery failed. This could either be due to your endpoint not returning a HTTP 200, or your endpoint taking more than 30 seconds to respond, or something else.|
|Sending||Message delivery in progress.|
|Will Not Send||Message delivery not attempted. The webhook endpoint was disabled (either by Fleetio or by a user).|