Webhooks Overview

Webhooks allow you to be notified when something happens in Fleetio. You can subscribe to many different Fleetio events and from that point on, Fleetio will send an HTTP POST request to your endpoint for each event occurrence. The POST request body will contain data about the event that occurred.

📘

Webhooks are only available on our Advanced plans

Setup & Configuration

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.

Timing & Delivery

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. So if 5 people edited the same vehicle within a minute, you will only get one message. This is done to prevent your endpoint from being overloaded. Events based on creation or deletion are fired off as soon as possible.

Webhook events are asynchronous. We will do our best to deliver them as soon as possible to your endpoint, so you should not rely on them for anything time sensitive. Your application should be prepared for delays in receiving messages, or even out of order messages if there are interruptions or delays in the network.

Please contact [email protected] if you experience delays longer than 1 hour.

Message Format

Fleetio will make a HTTP POST to your endpoint with a content type of application/json.
The body of the POST 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: "[email protected]",
  payload: {
    "id": 123,
    "current_meter_value": 110111.0,
    additional vehicle fields.....
  }
}

As you can see from the sample message, the payload will always contain the object that caused the webhook to fire. So if the event is vehicle_updated, the payload will contain a vehicle object. Similarly, if the webhook event is contact_created, the payload will contain a contact object.

Each message is timestamped by the timestamp attribute indicating when the event happened. This is a ISO8601 string, that is either the account's time zone or Central Time, if there is none set.

The triggered_by attribute is set to the user who triggered this webhook event. For example, if an issue was created, triggered_by would be set to the user who created the issue. Note that triggered_by can be null, if the event was generated by Fleetio as part of a background job.

Verifying Messages

In order to protect your endpoint from malicious hackers, Fleetio signs each message
with a shared key that you can find by selecting the "View Secret Key" action in the dropdown menu of your 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.

In order to verify that the message came from Fleetio, all you have to do is compute the HMAC SHA-256 digest of the raw HTTP body using the webhook secret as the key, and compare it 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)

Response

Your endpoint MUST respond with a 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 deliver the message to your endpoint. If none of these succeed, Fleetio will try once per hour for the next 24 hours. The timing of each attempt is described in the table below:

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 reenable the webhook under your Fleetio account settings.

Events

Fleetio will save all webhook events for 30 days. After 30 days of an event occurring, that event will be automatically removed. You can view all events that have been fired for your webhooks on the Webhook Events index page.

For a reference to all events Fleetio publishes, please go here.

Webhook Event Statuses