API Reference

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, Motive 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 Motive 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 Motive 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

Motive 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 and respond within 3 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. Motive will consider the request final and will not retry.
  • 403 - Indicates the HMAC signature could not be verified. Motive will consider the request invalid and will not retry.
  • 4XX or 5XX - Indicates the webhook was not processed and should be retried. Motive will retry the request based on the schedule below.

Possible Error Scenarios during webhook activation

  • Only one active webhook can be present with same action and url. Trying to activate one more webhook with same action and url will result in failure.
  • Only two active webhooks can be present for an action. Trying to activate more than two webhooks with same action will result in failure.

Timeouts

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

Retry Schedule

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

  • 1 minute
  • 1 hour
  • 6 hours

Enabling Webhooks (Test Requests)

Whenever you enable a webhook, change the URL, or change the shared secret, Motive 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)
  "vehicle_number": "sample",                      // the vehicle number present in motive
  "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
  "primary_fuel_level": 30.0,                      // indicates primary tank fuel level
  "secondary_fuel_level": 20.0                     // indicates secondary tank fuel level
}

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)
  "vehicle_number": "sample",                      // the vehicle number present in motive
  "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
  "primary_fuel_level": 30.0,                      // indicates primary tank fuel level
  "secondary_fuel_level": 20.0                     // indicates secondary tank fuel level
}

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": "J1939",
  "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",
  "occurrence_count": -1,
  "num_observations": 6,
  "sum_num_observations": 6,
  "source_address_name": null,
  "source_address": "1711",
  "is_sid": true,
  "fmi_description": "Abnormal rate of change",
  "dtc_status": null,
  "dtc_severity": null,
  "functional_grp_id": null,
  "ftb": null,
  "vehicle": {
    "id": 1,
    "number": "T123",
    "make": "Kenworth",
    "model": "379",
    "year": "2008",
    "vin": "ABC12345678909876",
    "metric_units": true
  },
  "eld_device": {
    "id": 1,
    "identifier": "00000001",
    "model": "lbb-2"
  },
  "network": "j1587/j1708"
}

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": "J1939",
  "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",
  "occurrence_count": -1,
  "num_observations": 6,
  "sum_num_observations": 6,
  "source_address_name": null,
  "source_address": "1711",
  "is_sid": true,
  "fmi_description": "Abnormal rate of change",
  "dtc_status": null,
  "dtc_severity": null,
  "functional_grp_id": null,
  "ftb": null,
  "vehicle": {
    "id": 1,
    "number": "T123",
    "make": "Kenworth",
    "model": "379",
    "year": "2008",
    "vin": "ABC12345678909876",
    "metric_units": true
  },
  "eld_device": {
    "id": 1,
    "identifier": "00000001",
    "model": "lbb-2"
  },
  "network": "j1587/j1708"
}

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"
  }
}

Driver Performance Event (driver_performance_event_created and driver_performance_event_updated)

Triggered when driver performance event is created or updated. Note: it would take minutes after the event has occurred for the payload to be eventually sent to the url.

{
  "action":"driver_performance_event_updated",
  "id":123,
  "acceleration":32.23,
  "end_bearing":110.95,
  "end_speed":23.868,
  "end_time":"2023-04-12T01:28:12Z",
  "lat":37.4121698,
  "lon":-121.9286528,
  "m_gps_heading":[
    114.53,
    113.91,
    113.15
  ],
  "m_gps_lat":[
    37.4119784,
    37.4119346,
    37.4118874
  ],
  "m_gps_lon":[
    -121.9282081,
    -121.9281022,
    -121.9279839
  ],
  "m_veh_odo":"nil",
  "m_veh_spd":[
    31.0,
    35.0,
    41.0
  ],
  "start_bearing":111.45,
  "start_speed":32.22,
  "start_time":"2023-04-12T01:28:11Z",
  "type":"hard_brake",
  "driver_id":1,
  "vehicle_id":12,
  "eld_device_id":123,
  "camera_media":{
    "id":321,
    "available":true,
    "cam_positions":[
      "front_facing",
      "driver_facing"
    ],
    "cam_type":"dc54",
    "uploaded_at":"2023-04-12T01:30:50Z",
    "start_time":"2023-04-12T01:28:04Z",
    "duration":15,
    "downloadable_videos":{
      "front_facing_enhanced_url":"nil",
      "front_facing_enhanced_ai_viz_url":"nil",
      "dual_facing_enhanced_url":"https://keep-truckin-preview.s3.amazonaws.com/uploads/camera_media/media/2436118/mp4-dual_facing-enhanced-7fa92a01-d7d1a59b",
      "dual_facing_enhanced_ai_viz_url":"nil",
      "front_facing_plain_url":"https://keep-truckin-preview.s3.amazonaws.com/uploads/camera_media/media/2436118/mp4-front_facing-7fa92a01-38c6-493b-ba3e27aa",
      "driver_facing_plain_url":"https://keep-truckin-preview.s3.amazonaws.com/uploads/camera_media/media/2436118/mp4-driver_facing-7fa92a01-38c6-493b-ba0b-5f3468c90c4a1de1f81e527bbaea69176acd25cce16c0968310"
    },
    "auto_transcode_status":"success",
    "downloadable_images":{
      "front_facing_jpg_url":"nil",
      "driver_facing_jpg_url":"nil"
    }
  },
  "m_gps_spd":[
    33.012,
    38.7,
    43.416
  ],
  "location":"San Jose, CA",
  "intensity":"-7.1 mph/s",
  "coaching_status":"pending_review",
  "coached_at":"nil",
  "coachable_behaviors":[
    "hard_brake"
  ],
  "coached_behaviors":"nil",
  "primary_behavior":[
    "hard_brake"
  ],
  "secondary_behaviors":[
    "no_tag_applies"
  ],
  "max_speed":58.86,
  "min_speed":0.0,
  "event_intensity":{
    "name":"Braking Intensity",
    "value":11.5,
    "unit_type":"acceleration"
  },
  "current_vehicle":{
    "id":117800,
    "number":"Sample"
  },
  "current_driver":{
    "id":983335,
    "first_name":"john",
    "last_name":"doe",
    "email":"john_doe@gmail.com",
    "driver_company_id":"john"
  },
  "metadata":{
    "additional_context":"nil",
    "annotation_tags":[
      "no_tag_applies"
    ],
    "severity":"low",
    "trigger":"nil"
  },
  "edited_by_fm":false
}

Speeding Event (speeding_event_created and speeding_event_updated)

Triggered when speeding event is created or updated. Note: it would take minutes after the event has occurred for the payload to be eventually sent to the url.

{
    "action": "speeding_event_created",
    "id": 435681,
    "max_over_speed_in_kph": 15.715800000000002,
    "avg_over_speed_in_kph": 12.358282941176471,
    "min_posted_speed_limit_in_kph": 48.2802,
    "max_posted_speed_limit_in_kph": 48.2802,
    "avg_vehicle_speed": 60.59663658536588,
    "min_vehicle_speed": 58.0001,
    "max_vehicle_speed": 63.996,
    "duration": 83,
    "start_lat": 43.0301183,
    "start_lon": -78.8308857,
    "end_lat": 43.0217879,
    "end_lon": -78.843557,
    "type": "posted",
    "start_time": "2023-04-17T13:46:04Z",
    "end_time": "2023-04-17T13:47:27Z",
    "coaching_status": "pending_review",
    "status": "invalid",
   "driver_id": 1,
   "vehicle_id":12,
   "eld_device_id": 123,
    "metadata": {
        "severity": "medium",
        "trigger": "speeding",
        "is_manually_changed": false
    }
}