Webhooks

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.

info

Please consult your plan to determine Webhook availability and limits for your account.

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.

Message Format

The POST request to your endpoint will have a Content-Type header of application/json.

The request body will contain a JSON message that looks like the following:

{
  id: 1,
  event: "vehicle_updated",
  timestamp: "2017-11-03T10:15:38.741-05:00",
  triggered_by: "ryoung@fleetio.com",
  payload: {
    "id": 123,
    "current_meter_value": 110111.0,
    . . .
  }
}

Attribute	Value	More Info
payload	The object which triggered the webhook.	Example: vehicle_updated event will contain a Vehicle object.
timestamp	ISO8601 string that reflects either the account's time zone, or Central Time if there is none set.	Indicates when the event occurred.
triggered_by	The User that triggered the event, or null*.	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 help@fleetio.com if you experience delays longer than 1 hour.

Debounced Events

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.

info

Events based on creation or deletion are fired off as soon as possible.

Message Verification

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:

1. Compute the HMAC SHA-256 digest of the raw HTTP body using the Webhook Secret Key.
2. Compare the computed digest with the X-Fleetio-Webhook-Signature HTTP header.

In Ruby, it would look like this:

OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha256'), webhook.shared_key, message.body)

Responding to Messages

Important

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.

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

info

Fleetio will keep record of webhook events for 30 days after an event occurred.

Webhook Event Statuses

Status	Description
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).