Overview

Overview of /company_webhooks

Webhooks allow you to be notified whenever certain actions occur within your fleet via an HTTP POST request to an endpoint of your choosing. If you have enabled webhooks for your fleet, KeepTruckin will make an HTTP POST request to your endpoint whenever the events you have setup occur.

One common use-case is vehicle location updates. If you want to be notified whenever a vehicle’s current location updates you could subscribe to the vehicle_location_updated action and you will receive a request whenever any vehicle’s location changes.

Webhook requests contain a JSON payload consisting of the action as well as any attributes relevant to the action. The list of currently support actions and their payloads are listed below.

Verifying Authenticity

Each webhook has a shared secret that KeepTruckin will use to sign the requests. The computed signature is included in the X-KT-Webhook-Signature HTTP header and can be used to verify that the request originated at KeepTruckin servers and has not been modified in-flight. You can respond with 403 if the signature does not match your computed expected value.

To compute the webhook signature, take the HMAC-SHA1 hex digest of the JSON payload using the shared secret.

["fault_code_closed"]
"d9d36bea41c44ae49d1bfc4a48ba2abe"

This would have an X-KT-Webhook-Signature HTTP header value of "f04a8386a21a6cba0447024e83b3f0983352bb72".

echo -n '["fault_code_closed"]' | openssl dgst -sha1 -hmac "f04a8386a21a6cba0447024e83b3f0983352bb72"
OpenSSL::HMAC.hexdigest(OpenSSL::Digest.new('sha1'), 'f04a8386a21a6cba0447024e83b3f0983352bb72', '["fault_code_closed"]')

Expected Responses

KeepTruckin servers expect specific responses from your server to indicate the successful receipt of a webhook. Make sure that your endpoint handler responds with the appropriate response code. Additionally, your server must accept the connection within 5 seconds and respond within 10 seconds or the request will be assumed to have failed. It is up to the endpoint handler to ensure that requests are only processed once.

  • 200 or 201 - Indicates the webhook was processed successfully. KeepTruckin will consider the request final and will not retry.
  • 403 - Indicates the HMAC signature could not be verified. KeepTruckin will consider the request invalid and will not retry.
  • 4XX or 5XX - Indicates the webhook was not processed and should be retried. KeepTruckin will retry the request based on the schedule below.

Timeouts

KeepTruckin servers expect specific responses from your server to indicate the successful receipt of a webhook within 3 seconds. If the KeepTruckin servers didn't get any response within 3 seconds, we timeout and put the webhook for retries.

Retry Schedule

KeepTruckin will make several attempts to retry failed requests using the following delays between attempts.

  • 10 seconds
  • 1 minute
  • 5 minutes
  • 10 minutes
  • 1 hour
  • 1 hour
  • 1 hour
  • 6 hours
  • 11 hours

Enabling Webhooks (Test Requests)

Whenever you enable a webhook, change the URL, or change the shared secret, KeepTruckin will perform a test request to verify a successful response is received. The webhook will only be enabled if a response code of 200 or 201 is received. The test request payload is always the same:

[vehicle_location_updated]

Supported Actions

Vehicle Current Location Updated (vehicle_location_updated)
Triggered whenever a vehicle location is received that is more recent than the current location.

{
  "action": "vehicle_location_updated",
  "trigger": "updated",
  "id": "5d3d5cf6-501f-4566-ad07-a80c05c743a7",    // unique identifier for the location object
  "vehicle_id": 123,                               // the vehicle id (foreign key)
  "located_at": "2017-01-01T12:00:00Z",            // time when the location was recorded (ISO8601 format)
  "lat": 34.123,                                   // latitude
  "lon": -84.123,                                  // longitude
  "bearing": 90.0,                                 // the direction of travel (0-360 degrees)
  "engine_hours": 123.56,                          // engine hours reported by the vehicle's ECU
  "speed": 123.5,                                  // speed reported by the vehicle's ECU
  "odometer": 2343232.23,                          // odometer reading reported by the vehicle's ECU
  "fuel": 23423.23,                                // amount of fuel used reported by the vehicle's ECU
  "type": "vehicle_moving",                        // indicates whether the location was captured when the vehicle started moving, stopped moving, the engine started or stopped, or while already in motion
  "description": "3.2 mi SE of San Francisco, CA"  // description of the location
}

Vehicle Location Received (vehicle_location_received)
Triggered for all vehicle locations received regardless of whether they are the most recent or not.

{
  "action": "vehicle_location_received",
  "trigger": "created",
  "id": "5d3d5cf6-501f-4566-ad07-a80c05c743a7",    // unique identifier for the location object
  "vehicle_id": 123,                               // the vehicle id (foreign key)
  "located_at": "2017-01-01T12:00:00Z",            // time when the location was recorded (ISO8601 format)
  "lat": 34.123,                                   // latitude
  "lon": -84.123,                                  // longitude
  "bearing": 90.0,                                 // the direction of travel (0-360 degrees)
  "engine_hours": 123.56,                          // engine hours reported by the vehicle's ECU
  "speed": 123.5,                                  // speed reported by the vehicle's ECU
  "odometer": 2343232.23,                          // odometer reading reported by the vehicle's ECU
  "fuel": 23423.23,                                // amount of fuel used reported by the vehicle's ECU
  "type": "vehicle_moving",                        // indicates whether the location was captured when the vehicle started moving, stopped moving, the engine started or stopped, or while already in motion
  "description": "3.2 mi SE of San Francisco, CA"  // description of the location
}

Vehicle Created or Updated (vehicle_upserted)
Triggered whenever a vehicle is created or updated.

{
  "action": "vehicle_upserted",
  "trigger": "created",                   // possible values (created, updated) indicates whether vehicle was created or updated
  "id": 123,
  "company_id": 456,
  "number": "T123",
  "status": "active",
  "ifta": true,
  "vin": "ABC12345678909876",
  "make": "Kenworth",
  "model": "379",
  "year": "2008",
  "license_plate_state": "CA",
  "license_plate_number": "7ABD123",
  "metric_units": false,
  "fuel_type": "diesel",
  "prevent_auto_odometer_entry": false,
  "eld_device_id": 1,
  "eld_device": {
    "id": 1,
    "identifier": "00000001",
    "model": "lbb-2"
  },
  "current_driver": {
    "id": 1,
    "first_name": "Bob",
    "last_name": "Smith",
    "driver_company_id", "1223"
  }
}

Fault Code Opened (fault_code_opened)
Triggered whenever a new fault code is opened on a vehicle.

{
  "action": "fault_code_opened",
  "trigger": "created",
  "id": 123,
  "code_description": "Cargo Securement",
  "status": "open",
  "first_observed_at": "2017-01-01T12:45:33Z",
  "last_observed_at": "2017-01-05T12:45:33Z",
  "type": "constant",
  "fmi": 5,
  "code_label": "SPN-5610",
  "source_address_label": "Fuel System",
  "vehicle": {
    "id": 1,
    "number": "T123",
    "make": "Kenworth",
    "model": "379",
    "year": "2008",
    "vin": "ABC12345678909876"
  },
  "eld_device": {
    "id": 1,
    "identifier": "00000001",
    "model": "lbb-2"
  }
}

Fault Code Closed (fault_code_closed)
Triggered whenever an existing fault code is closed on a vehicle.

{
  "action": "fault_code_closed",
  "trigger": "updated",
  "id": 123,
  "code_description": "Cargo Securement",
  "status": "closed",
  "first_observed_at": "2017-01-01T12:45:33Z",
  "last_observed_at": "2017-01-05T12:45:33Z",
  "type": "constant",
  "fmi": 5,
  "code_label": "SPN-5610",
  "source_address_label": "Fuel System",
  "vehicle": {
    "id": 1,
    "number": "T123",
    "make": "Kenworth",
    "model": "379",
    "year": "2008",
    "vin": "ABC12345678909876"
  },
  "eld_device": {
    "id": 1,
    "identifier": "00000001",
    "model": "lbb-2"
  }
}

User Created or Updated (user_upserted)
Triggered whenever a user is created or updated in your fleet.

{
  "action": "user_upserted",
  "trigger": "updated",                // possible values (created, updated) indicates whether user was created or updated
  "id": 123,
  "role": "driver",
  "status": "active",
  "email": "test.driver@example.com",
  "username": "",
  "first_name": "Test",
  "last_name": "Driver",
  "driver_company_id": "ABC123",
  "phone": "(650) 555-5555",
  "phone_ext": null,
  "carrier_name": "My Fleet",
  "carrier_street": "123 Main St",
  "carrier_city": "San Francisco",
  "carrier_state": "CA",
  "carrier_zip": "94104",
  "terminal_street": null,
  "terminal_city": null,
  "terminal_state": null,
  "terminal_zip": null,
  "time_zone": "Pacific Time (US & Canada)",
  "cycle": "70_8",
  "exception_24_hour_restart": false,
  "exception_8_hour_break": false,
  "exception_wait_time": false,
  "exception_short_haul": false,
  "exception_ca_farm_school_bus": false,
  "cycle2": "70_7",
  "exception_24_hour_restart2": false,
  "exception_8_hour_break2": false,
  "exception_wait_time2": false,
  "exception_short_haul2": false,
  "exception_ca_farm_school_bus2": false,
  "eld_mode": "logs",
  "drivers_license_number": "",
  "drivers_license_state": "",
  "yard_moves_enabled": true,
  "personal_conveyance_enabled": false
}

Inspection Report Created or Updated (inspection_report_upserted)
Triggered whenever a vehicle inspection report (DVIR) is created or updated.

{
  "action": "inspection_report_upserted",
  "trigger": "created",                         // possible values (created, updated, deleted) indicates whether inspection report was created, updated or deleted
  "id": 123,
  "date": "2017-01-01",
  "time": "13:45:33",
  "odometer": 12345,
  "carrier_name": "My Fleet",
  "trailer_nums": ["TR-123"],
  "location": "1.6 mi SW of San Francisco, CA",
  "status": "satisfactory",
  "driver_signed_at": "2017-01-02T06:23:22Z",
  "mechanic_signed_at": "2017-01-03T13:34:12Z",
  "reviewer_signed_at": "2017-01-03T15:23:22Z",
  "vehicle_number": "T123",
  "vehicle": {
    "id": 1,
    "number": "T123",
    "make": "Kenworth",
    "model": "379",
    "year": "2008",
    "vin": "ABC12345678909876"
  },
  "driver": {
    "id": 1,
    "first_name": "Bob",
    "last_name": "Smith",
    "driver_company_id", "1223"
  },
  "mechanic": {
    "id": 2,
    "first_name": "Russ",
    "last_name": "Jones"
  },
  "reviewer": {
    "id": 3,
    "first_name": "Jim",
    "last_name": "Wilson",
    "driver_company_id", "3234"
  },
  "defects": [
    {
      "id": 123,
      "area": "tractor",
      "category": "Belts and Hoses",
      "notes": ""
    }
  ]
}

HOS Violation Created or Updated (hos_violation_upserted)
Triggered whenever a HOS violation is created or updated.

{
  "action": "hos_violation_upserted",
  "trigger": "updated",                 // possible values (created, updated, deleted) indicates whether inspection report was created, updated or deleted
  "id": 123,
  "type": "driving_11",
  "name": "11 Hour Driving Limit",
  "start_time": "2017-01-04T17:23:00Z",
  "end_time": "2017-01-04T18:00:00Z",
  "driver": {
    "id": 1,
    "first_name": "Bob",
    "last_name": "Smith",
    "driver_company_id", "1223"
  }
}

Vehicle Enter/Exit Geofence (vehicle_geofence_event)
Triggered whenever a Vehicle Enters or Exits into a Geofence.

{
  "event_type": "geofence_exit", // possible values: geofence_entry, geofence_exit
  "id": 45055326,
  "geofence_id": 213308,
  "start_time": "2021-10-12T02:53:15Z",
  "end_time": "2021-10-12T19:30:45Z",
  "duration": 59850, 
  "vehicle": {
    "id": 740263,
    "number": "sivanesh_AI_car",
    "year": "2010",
    "make": "",
    "model": "",
    "vin": "WMWMF7C52ATX43675"
  },
  "start_driver": {
    "id": 2689212,
    "first_name": "Sivanesh_ai",
    "last_name": "Manoharan_ai",
    "username": "sivaneshai",
    "email": "sivanesh.manoharan+ai@keeptruckin.com",
    "driver_company_id": "",
    "role": "driver"
  },
  "end_driver": {
    "id": 2689212,
    "first_name": "Sivanesh_ai",
    "last_name": "Manoharan_ai",
    "username": "sivaneshai",
    "email": "sivanesh.manoharan+ai@keeptruckin.com",
    "driver_company_id": "",
    "role": "driver"
  },
  "action": "vehicle_geofence_event"
}

Asset Enter/Exit Geofence (asset_geofence_event)
Triggered whenever an Asset Enters or Exits into a Geofence.

{
  "action": "asset_geofence_event",
  "event_type": "geofence_exit", // possible values: geofence_entry, geofence_exit
  "id": 3123212,
  "geofence_id": 110882,
  "start_time": "2021-10-12T13:39:55Z",
  "end_time": "2021-10-12T13:43:19Z",
  "duration": 204,
  "asset_details": {
    "asset_id": 220,
    "name": "AG552_AT4-Q1G-ZKD",
    "type": "curtain_side",
    "vin": "AG-11111111111112",
    "make": "Great Dane",
    "model": "Champion CL",
    "year": "2015",
    "company_id": 160,
    "asset_gateway": {
      "id": 349,
      "identifier": "AT4-Q1G-ZKD"
    }
  }
}

Engine Toggle Event (engine_toggle_event)
Triggered whenever a vehicle starts or stops its engine.

{
  "action": "engine_toggle_event",
  "trigger": "on",                   // possible values (on, off) indicates engine status
  "vehicle_id": 123,
  "company_id": 456,
  "vehicle_number": "T123",
  "vin": "ABC12345678909876",
  "make": "Kenworth",
  "model": "379",
  "year": "2008",
  "license_plate_state": "CA",
  "license_plate_number": "7ABD123",
  "metric_units": false,
  "fuel_type": "diesel",
  "eld_device_id": 1,
  "eld_device": {
    "id": 1,
    "identifier": "00000001",
    "model": "lbb-2"
  },
  "current_driver": {
    "id": 1,
    "first_name": "Bob",
    "last_name": "Smith",
    "driver_company_id", "1223"
  }
}