Webhook Payloads

Webhooks let you subscribe to a real-time stream of location, and trip status data generated by HyperTrack. Rather than making an API call, HyperTrack can send an HTTPS request to an endpoint that you specify. Events are published for all devices associated with the account.

The HyperTrack mobile SDKs send a time-series of events from the device to the HyperTrack server. These events are processed and then posted to your servers on Webhooks. A webhook is an HTTPS POST call from the HyperTrack servers to a configurable destination.

After receiving a webhook on your own server, you can trigger updates on your mobile or web apps in near real-time and implement your live location features.

Setting up HyperTrack Webhooks requires configurations on your server and the HyperTrack dashboard.

The server receiving webhooks needs to be configured appropriately to consume webhooks.

Static Endpoint URL

Your server needs to expose a public HTTPS endpoint capable of receiving external, incoming requests. It is important to have a static endpoint URL that will be accessible at all times.

HTTPS POST Method

Webhooks are realized through HTTPS POST requests to the configured endpoint. Your server needs to support this method and be able to parse the payload provided with the request.

📘

If you are running a local development environment, please refer to tools like https://github.com/localtunnel/localtunnel to expose your local endpoints through HTTPS.

JSON Payload

The payload you will receive with POST requests is formatted in JSON. You need to implement the capability to parse JSON objects in order to leverage the HTTP request body content.

You should use a JSON parser that handles converting the escaped representation of control characters back to their ASCII character values (for example, converting \n to a newline character). This is critical if you want to verify the signature of a webhook.

Payload and Headers

Webhooks from HyperTrack will be sent with headers and a JSON payload. Please ensure to verify the headers and implement your server to handle these correctly.

Header: Content-Type

The header is set to application/json for all webhooks. Please ensure to parse every webhook with this content type. The actual content is represented in JSON.

Header: x-hypertrack-signature

HyperTrack signs each webhook POST request. Please see this guide for further instructions.

Responding to webhooks

Make sure to respond to HyperTrack webhooks with the appropriate status code. The connection will time out in 10 seconds. If your endpoint does not respond before the connection times out or if your endpoint returns a status code outside the range of 200–4xx, HyperTrack will consider the delivery of the webhook as a failed attempt and retry as described below.

Retry algorithm

If HyperTrack doesn't receive a successful response from your server, it attempts to deliver the webhook again. By default, if the initial delivery of the webhook fails, HyperTrack attempts up to three retries with a delay between failed attempts set at 20 seconds.

The retries will always refer to the same x-amz-sns-message-id. By comparing the IDs of the webhooks you have processed with incoming webhooks, you can understand whether the message is a retry attempt.

Order of webhooks

HyperTrack will attempt to deliver webhooks in the same order they were received. However, network issues could potentially result in out-of-order webhooks.

Before handling events, you should compare the recorded_at property of the JSON payload and ensure to store events in the order they were recorded as opposed to when they were received.

Webhook Payload

The overall POST payload has a static structure. The type of the webhook indicates the structure of the data object.

[
  {
  "created_at": "2019-02-27T22:50:29.000000Z",
  "data": { ... },
  "location": { ... },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "recorded_at": "2019-02-27T22:50:24.000000Z",
  "type": "",
  "version": "2.0.0"
  }
]
NameTypeDescription
device_idstringUnique device identifier, case sensitive (Present where the webhook originates from a device)
created_atstringISO 8601 date and time when webhook was sent (server timestamp)
recorded_atstringISO 8601 date and time when event was recorded (client timestamp). Not available for trip webhooks (e.g. start and completion)
typestringType of webhook data. Can be one of the types below (location, device_status, battery, trip, registration_update, reinstall, geotag, geofence, order). More types might be added over time.
dataobjectData corresponding to the type. See detailed description below.
locationobjectGeoJSON object with type and coordinates. Provided as context to trip delay webhooks only
versionstringVersion string of the webhook.

Depending on the type of webhook, the JSON payload will vary. However, the overall structure is fixed.

The Webhook POST body is always an array of JSON objects. Please ensure to iterate over all webhooks sent per request.

Currently, the following types are supported:

FeatureTypeDescription
LocationslocationLocation stream
Device Statusdevice_statusDevice status changes (active, inactive, disconnected and activity changes)
BatterybatteryBattery changes (low, normal and charging)
TripstripTrip start, destination arrival, destination exit, trip delays, and trip completion events
GeotagsgeotagGeotags stream
OrdersorderOrders lifecycle changes like order start, completion, cancellation, eta change etc

Device Status Payload

{
   "device_id":"AAAAAAAA-7101-48A9-86C4-B762993ACC5A",
   "driver_handle": "ram@124",
   "recorded_at":"2021-10-27T00:40:53.811Z",
   "metadata":{
      "invite_id":"https://hypertrack-logistics.app.link/xxxx",
      "email":"[email protected]"
   },
   "version":"2.0.0",
   "location":{
      "type":"Point",
      "coordinates":[
         -122.503655,
         37.76097,
         24.98
      ]
   },
   "created_at":"2021-10-27T00:42:01.166509Z",
   "name":"Alex",
   "data":{
      "value": "inactive",
      "outage_category": "behavioural",
      "outage_code": "location_permissions_denied",
      "outage_label": "Location permissions denied",
      "outage_description": "The worker explicitly denied permissions in response to system prompt or in Settings > App Name > Location on iOS. On Android, the worker should change location permission to 'Allow' in App Info > Permissions > Location.",
      "location_start": {
        "type": "Point",
        "coordinates":[
            -122.503655,
            37.76097,
            24.98
        ]
      },
      "recorded_at_start": "2021-10-27T00:40:53.811Z"
   },
   "type":"device_status"
}
NameTypeDescription
data.valuestringDevice status. One of active, inactive or disconnected. Please read here to understand how HyperTrack tracks device status.
data.activitystringFor active devices only, can be one walk,drive, or stop
data.outage_categoryenumYesadversarial, behavioral, sporadic, os, reachability
data.outage_labelstringYes
data.outage_codestringYes
data.outage_descriptionstringYes
data.startobjectAvailable in case of data.value is active and an activity has been completed, Gives information of when and where the activity started
data.endobjectAvailable in case of data.value is active and an activity has been completed, Gives information of when and where the activity ended
data.distanceintAvailable in case of data.value is active and an activity has been completed
data.durationintAvailable in case of data.value is active and an activity has been completed
locationobjectLocation in GeoJSON format
location.typestringAs of right now, only Point is supported
location.coordinatesarrayArray of longitude latitude and (optional) altitude (in m)

Driver Outage Payload

{
  "type": "driver",
  "data": {
    "value": "outage",
    "outage_category": "behavioural",
    "outage_code": "location_permissions_denied",
    "outage_label": "Location permissions denied",
    "outage_description": "The worker explicitly denied permissions in response to system prompt or in Settings > App Name > Location on iOS. On Android, the worker should change location permission to 'Allow' in App Info > Permissions > Location.",
    "location_start": {
			"type": "Point",
      "coordinates": [
       -122.503655,
       37.76097,
       24.98
      ]
    },
   "recorded_at_start": "2021-10-27T00:40:53.811Z",
   "location_end": {
     "type": "Point",
      "coordinates": [
       -122.504655,
       37.76197,
       24.98
      ]
   },
    "recorded_at_end": "2021-10-27T01:00:53.811Z",
    "detail": {
      "distance": 0,
      "duration": 1200
    }
  },
  "driver_handle": "ram@123"
}
PropertyTypeRequiredDescriptionEnum / Reference
typeenumYesdriver
driver_handlestringYes
dataobject
→ outage_categoryenumYesadversarial, behavioral, sporadic, os, reachability
→ outage_labelstringYes
→ outage_codeenumYes
→ outage_descriptionstringYes
→ location_startobject
→ recorded_at_startstringYes
→ location_endobject
→ recorded_at_endstring
→valueenumYesoutage
→detailobject
→→ durationinteger
→→ distanceinteger

Battery Payload

2.0.0 Payload

[
  {
   "created_at":"2019-07-01T20:00:01.247377Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "recorded_at":"2019-07-01T20:00:00.000000Z",
   "type":"battery",
   "data":{
      "value":"low"
     },
   "location":{
      "type":"Point",
      "coordinates":[
         -6.2755,
         57.6398983124
      ]
     },
   "version":"2.0.0"
  }
]
NameTypeDescription
data.valuestringBattery status. Values include low, normal and charging
locationobjectLocation in GeoJSON format
location.typestringAs of right now, only Point is supported
location.coordinatesarrayArray of longitude latitude and (optional) altitude (in m)

2.1.0 Payload

[
  {
   "created_at":"2021-12-21T20:36:37.752Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "recorded_at":"2021-12-21T20:36:34.410Z",
   "type":"battery",
   "data":{
      "value":"low",
      "battery_percent":75
     },
   "version":"2.1.0"
  }
]
NameTypeDescription
data.valuestringBattery status. Values include low, normal and charging
data.battery_percentintBattery percentage

📘

2.1.0 battery payloads require a minimal a SDK version of 4.9.0 for iOS and 5.4.1 for Android.

Time Offset Payload

This webhook payload is sent whenever the driver performs a manual change on the device in a possible attempt to mis-represent timing for the order in progress. Once the offset is detected to be longer than 10 minutes, the webhook event is sent with the payload as described below.

3.0.0 Payload

[
  {
 "device_id": "D6A48382-3B4E-47FF-A533-3FF71A52E05E",
 "recorded_at": "2024-01-20T18:09:29.583145215Z",
 "created_at": "2024-01-20T18:09:32.017Z",
 "data": {
  "user_time": "2024-01-20T19:09:13.818Z",
  "value": 3584.235
     },
 "type": "time_offset_changed",
 "version": "3.0.0"
  }
]
NameTypeDescription
data.valuestringTime offset from the current time versus time set by the app user.
data.user_timeobjectTime set by the user, in UTC

📘

time_offset_changed require a minimal a SDK version of 5.3.0 for iOS and 7.3.0 for Android.

Trip Payload

[
  {
  "created_at": "2019-07-01T14:00:00.000000Z",
  "data": {
    "value": "created",
    "trip_id": "123E4567-E89B-12D3-A456-426655440000",
    "trip_metadata": { "customer": "1234" }
  },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "type": "trip",
  "version": "2.0.0"
  }
]

If you start trips, you will receive trip events whenever ...

  • a new trip is created successfully
  • a device enters or exits a trip destination
  • a trip with a scheduled arrival time is estimated to be delayed
  • a trip is completed successfully and a summary is available
  • when there is change in ETA (change in minutes described as integer)

📘

Trip start and completion webhooks do not have a "recorded_at" property because the recording time equals the creation time due to server-side operations.

NameTypeDescription
data.valuestringOne of: created, destination_arrival, destination_exit, delayed, first_eta, eta_change or completed
data.trip_idstringUnique identifier of the trip, case sensitive
data.trip_metadataObjectMetadata that you have assigned to this trip (optional)
data.arrive_atstringTimestamp with new arrived date, only available if value is delayed
data.remaining_durationintTime remaining (in seconds) as per ETA calculations, only available if value is eta_change or first_eta
data.remaining_distanceintDistance remaining (in meters) as per ETA calculations, only available if value is eta_change or first_eta
data.destination_idstringUnique identifier of the trip destination, case sensitive (Only available for trips with multiple orders)
data.destination_metadataObjectMetadata that you have assigned to the trip destination (Only available for trips with multiple orders)
data.durationintDuration of trip (in seconds), only available if value is completed
data.distanceintDistance travelled during trip (in meters), only available if value is completed
data.duration_at_destinationintDuration spent at the destination before trip completion, only available if value is completed

Device Registration Payload

[
  {
  "created_at": "2020-07-01T14:00:00.000000Z",
  "data": {
    "value": "registration"
  },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "type": "registration",
  "version": "2.0.0"
  }
]

This webhook is generated when a new device is registered for the first time with the hypertrack platform.

NameTypeDescription
data.valuestringLabel indicating registration

Device Registration Update Payload

[
  {
  "created_at": "2020-07-01T14:00:00.000000Z",
  "data": {
    "value": "device_info"
  },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "name": "Thomas Phone",
  "metadata": { "driver_id": 1234 },
  "type": "registration_update",
  "version": "2.0.0"
  }
]

This webhook is generated when a new device updates its device information, which also may include name and/or its metadata.

NameTypeDescription
data.valuestringLabel indicating device information update

Host Application Reinstallation Payload

[
  {
  "created_at": "2020-07-01T18:00:00.000000Z",
  "data": {
    "value": "reinstall"
  },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "type": "reinstall",
  "version": "2.0.0"
  }
]

This webhook is generated when a device performs a reinstallation of the application integrated with the Hypertrack SDK.

NameTypeDescription
data.valuestringLabel indicating reinstallation

Geotag Payload

[
  {
  "created_at": "2019-07-01T14:01:00.000000Z",
  "recorded_at": "2019-07-01T14:00:00.000000Z",
  "data": {
    "order_handle": "order-1",
    "geotag_type": "arrived",
    "metadata": { "orderId": "123490809808" },
     "deviation": 14,
     "distance": 238,
     "duration": 63,
     "location": {
        "type": "Point",
        "coordinates": [ -6.2755, 57.6398983 ]
     },
    "expected_location": {
      "type": "Point",
      "coordinates": [ -6.2756, 57.6398983 ]
    },
    "driver_handle": "James"
  },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "type": "geotag",
  "version": "3.0.0"
  }
]
NameTypeDescription
data.order_handlestringUnique identifier for an order
data.geotag_typestringLabel identifying a segment of order fulfillment
data.driver_handlestringUnique identifier for a driver
data.metadataObjectMetadata that you have assigned to this geotag (optional)
data.locationObjectLocation in GeoJSON format
data.expected_locationObjectLocation in GeoJSON format
data.location.typestringAs of right now, only Point is supported
data.location.coordinatesarrayArray of longitude latitude and (optional) altitude (in m)
data.expected_location.typestringAs of right now, only Point is supported
data.expected_location.coordinatesarrayArray of longitude latitude and (optional) altitude (in m)
data.deviationintDeviation between expected location and actual location
data.distanceintDistance travelled since last geotag
data.durationintTime since last geotag

Geofence Payload

[
  {
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "driver_handle": "James",
  "data": {
    "arrival": {
      "location": {
        "coordinates": [
          -122.394223, 37.792763, 822.58
        ],
        "type": "Point"
      },
      "recorded_at": "2021-07-15T13:29:21.085Z"
    },
    "duration": 3738,
    "exit": {
      "location": {
        "coordinates": [
          -122.394223, 37.792763, 822.58
        ],
        "type": "Point"
      },
      "recorded_at": "2021-07-15T14:31:38.789Z"
    },
    "geofence_id": "00001111-d30d-4a4a-b965-95f3f743256e",
    "geofence_metadata": {
      "name": "Main store"
    },
    "place_handle": "Store-North-Square",
    "geometry": {
      "coordinates": [
        -122.394223, 37.792763

      ],
      "type": "Point"
    },
    "marker_id": "00001111-b97b-490d-8d04-a539477df0be",
    "radius": 50,
    "route_to": {
      "distance": 1234,
      "duration": 3600,
      "idle_time": 1800,
      "prev_marker_id": "00001111-2dac-40a7-973b-9e3d66898a7d",
      "started_at": "2021-07-15T12:29:16.424Z"
    },
    "value": "exit"
  },
  "location": {
    "type": "Point",
    "coordinates": [
      -122.394223,
      37.792763
    ]
  },
  "recorded_at": "2021-07-15T13:29:21.085Z",
  "created_at": "2021-07-15T13:29:21.085Z",
  "version": "2.0.0",
  "type": "geofence"
  }
]
NameTypeDescription
device_idstringUnique device identifier, case sensitive
driver_handlestringUnique identifier for a driver
data.arrivalobjectObject representing details about the geofence arrival
data.arrival.locationobjectLocation object that triggered geofence arrival
data.arrival.location.typestringAs of right now, only Point is supported
data.arrival.location.coordinatesarrayArray of longitude, latitude and (optional) elevation
data.arrival.recorded_atstringISO 8601 date when the location triggering arrival was recorded
data.exitobjectObject representing details about the geofence exit. Does not exist when the user is still inside the geofence. {optional}
data.exit.locationobjectLocation object that triggered geofence exit. Only set when geofence was exited due to a location. Can be empty when marker was closed to due a health event. (optional)
data.exit.location.typestringAs of right now, only Point is supported
data.exit.location.coordinatesarrayArray of longitude, latitude and (optional) elevation
data.exit.recorded_atstringISO 8601 date when the event triggering exit was recorded
data.durationintDuration of the visit in [seconds]
data.geometryObjectGeofence geometry of the geofence creating this marker
data.marker_idStringUnique identifier for this geofence marker
data.place_handleStringUnique Identifier of the place for which entry/exit is recorded. It will be present if geofence is associated with a place created via Places API
data.route_toobjectObject describing the route since last geofence marker (optional)
data.route_to.distanceintDistance travelled since last geofence marker or start of tracking session in [meters]
data.route_to.durationintDuration since last geofence marker or start of tracking session in [seconds]
data.route_to.idle_timeintDuration at stops since last geofence marker or start of tracking session in [seconds]
data.route_to.started_atStringISO 8601 Date and time when route_to calculation started
data.valueString'entry' - value indicating entry inside geofence
'exit' - value indicating exit from geofence
'delete' - value indicating that previously sent out visit was removed due to more accurate ground truth arriving*
locationobjectDeprecated legacy payload, new users will find it null

[*] we are adjusting geofence visits as data arrives - we get more ground truth from the sdk which can lead us to classify a previous visit as not a meaningful enough (e.g., a drive through).
our customers also rely on the detection to have low latencies. so we can't wait for all the data to arrive and the create the visits.
that's why in same cases, we send a geofence visit out and then later delete it again. it's rare that this happens

Order Webhooks

Webhooks are sent at different stages of an order's lifecycle. Sample webhook payloads for each of order lifecycle stages can be found below.

Order Planning Started Webhook

Order Planning Started Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"planning_started",
      "planning_sequence_number": 1,
      "plan_id": "f9212af2-71e8-40f0-84bd-005424a80a4d",
      "planning_started_reason": "api",
      "started_at": "2021-01-01T14:00:00.000000Z",
      "ops_group_handle": "OPS_123"
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesplanning_started
data.planning_sequence_numberintegerYesSequence Number of the plan for this specific plan ID
data.plan_idstringYesUnique identifier of the plan which is getting planned
data.planning_started_reasonstringYesTrigger reason for this specific planning
data.started_atstringYesTimestamp at which plan was started
data.ops_group_handlestringYesOps group handle for which the planning is triggered

Order Planning Completed Webhook

Order Planning Completed Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"planning_completed",
      "planning_sequence_number": 1,
      "plan_id": "f9212af2-71e8-40f0-84bd-005424a80a4d",
      "num_orders": 10,
      "num_routes": 2,
      "num_unplanned_orders": 2,
      "completed_at": "2021-01-01T14:01:00.000000Z",
      "route_handles_created": ["6784e919-71e8-40f0-84bd-005424a80a4d"],
      "route_handles_modified": ["f9212af2-7168-4f61-b686-2020f547637f"],
      "started_at": "2021-01-01T14:00:00.000000Z",
      "ops_group_handle": "OPS_123"
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesplanning_completed
data.planning_sequence_numberintegerYesSequence Number of the plan for this specific plan ID
data.plan_idstringYesUnique identifier of the plan which is getting planned
data.num_ordersintegerYesNumber of Orders planned
data.num_ordersintegerYesNumber of Orders planned
data.num_routesintegerYesNumber of Routes planned
data.num_unplanned_ordersintegerYesNumber of Orders which could not be planned
data.started_atstringYesTimestamp at which plan was started
data.completed_atstringYesTimestamp at which plan was completed
data.route_handles_createdstringYesRoute handles which got created in this planning instance
data.route_handles_modifiedstringYesRoute handles which got modified in this planning instance
data.ops_group_handlestringYesOps group handle for which the planning is triggered

Order Planning Failed Webhook

Order Planning Failed Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"planning_failed",
      "planning_sequence_number": 1,
      "plan_id": "f9212af2-71e8-40f0-84bd-005424a80a4d",
      "failure_reason": "No Available Drivers",
      "num_orders": 10,
      "num_unplanned_orders": 2,
      "started_at": "2021-01-01T14:00:00.000000Z",
      "ops_group_handle": "OPS_123"
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesplanning_failed
data.planning_sequence_numberintegerYesSequence Number of the plan for this specific plan ID
data.plan_idstringYesUnique identifier of the plan which is getting planned
data.num_ordersintegerYesNumber of Orders planned
data.failure_reasonstringYesFaiure reason for Planning
data.num_unplanned_ordersintegerYesNumber of Orders which could not be planned
data.started_atstringYesTimestamp at which plan was started
data.ops_group_handlestringYesOps group handle for which the planning is triggered

Order Started Webhook

Order Started Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"started",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesstarted
data.order_handlestringYesUnique handle for the Order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.route_handlestringYesUnique identifier of the route containing the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order

Order Assigned Webhook

Order Assigned Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"assigned",
      "order_handle":"DGC127092",
      "assigned_at": "2021-01-01T14:00:00.000Z",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "assign_source": "automated",
      "status":"assigned",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesassigned
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.assigned_attimestampYesTimestamp indicating when the order was assigned
data.statusstringYesStatus of the order - assigned
data.assign_sourceenumNoEnumerated string to distinguish how did the order get assigned, either manual or automated
data.metadataobjectNoMetadata that you have assigned to this order

Order First ETA Webhook

Order First ETA Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"first_eta",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "remaining_distance": 2582,
      "remaining_duration": 410,
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesfirst_eta
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.remaining_distanceintYesDistance remaining in meters
data.remaining_durationintYesTime remaining to reach destination as per current location in seconds

Order ETA Change Webhook

Order ETA Change Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"eta_change",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "remaining_distance": 2382,
      "remaining_duration": 359,
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYeseta_change
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.remaining_distanceintYesDistance remaining in meters
data.remaining_durationintYesTime remaining to reach destination as per current location in seconds

Order Delayed Webhook

Order Delayed Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"delayed",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        },
      "arrive_at":"2021-01-01T14:25:00.000000Z",
      "scheduled_at":"2021-01-01T14:23:00.000000Z",
      "initial_eta":"2021-01-01T14:20:00.000000Z"
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesdelayed
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.arrive_attimestampYesTimestamp indicating the new expected arrival time
data.scheduled_attimestampNoTimestamp indicating the provided scheduled time for order fulfillment
data.initial_etatimestampNoTimestamp indicating the initial expected arrival time

Order N-Minutes away Webhook

Order N-Minutes away Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"n_minutes_away",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "remaining_distance": 2164,
      "remaining_duration": 300,
      "remaining_minutes": 5,
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesn_minutes_away
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.remaining_distanceintYesDistance remaining in meters
data.remaining_durationintYesTime remaining to reach destination as per current location in seconds
data.remaining_minutesintYesTime remaining in minutes (by default webhook is sent when order is 60 min away or 15 min away)

Order Disabled Webhook

Order Disabled Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"disabled",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"disabled",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesdisabled
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - disabled
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order

Order Enabled Webhook

Order Enabled Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"enabled",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesenabled
data.order_handlestringYesUnique handle for the Order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.route_handlestringYesUnique identifier of the route containing the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order

Order Updated Webhook

Order Updated Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"updated",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesupdated
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order

Order Arrived Webhook

Order Arrived Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"arrived",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "place_handle": "Store-North-Square",
      "arrival": {
        "location": {
           "coordinates": [-6.2785, 57.6388983, 0],
           "type": "Point"
          },
        "recorded_at": "2021-01-01T14:05:10.000000Z"
        },
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
			"scheduled_at":"2021-01-01T14:23:00.000000Z",
      "initial_eta":"2021-01-01T14:20:00.000000Z",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesarrived
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.place_handlestringNoUnique Identifier of the place for which exit is recorded. It will be present if order is associated with a place created via Places API
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.scheduled_attimestampNoTimestamp indicating the provided scheduled time for order fulfillment
data.initial_etatimestampNoTimestamp indicating the initial expected arrival time
data.arrivalobjectYesContains location and recorded_at timestamp of the arrival

Order Exited Webhook

Order Exited Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"exited",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "place_handle": "Store-North-Square",
      "exit": {
        "location": {
           "coordinates": [-6.2785, 57.6388983, 0],
           "type": "Point"
          },
        "recorded_at": "2021-01-01T14:05:10.000000Z"
        },
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesexited
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.place_handlestringNoUnique Identifier of the place for which exit is recorded. It will be present if order is associated with a place created via Places API
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.exitobjectYesContains location and recorded_at timestamp of the exit from the order destination location. Location can be empty when marker was closed to due an outage.

Order Completed Webhook

Order Completed Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"completed",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "distance":1834,
      "duration":408,
      "deviation":75,
      "actual_service_time": 35,
      "status":"completed",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYescompleted
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - completed
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.distanceintYesTotal distance travelled to fulfill the order
data.durationintYesTotal time in seconds since order start
data.deviationintYesDeviation between order destination location and actual location where the order is completed
data.actual_service_timeintNoTotal time spent by driver at the destination, in case the completion happened after the arrival

Order Cancelled Webhook

Order Cancelled Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"cancelled",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "distance":1834,
      "duration":408,
      "status":"cancelled",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYescompleted
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - completed
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.distanceintYesTotal distance travelled to fulfill the order
data.durationintYesTotal time in seconds since order start

Orders at risk Payload

Order at risk Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"risk_updated",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
			"risks":{
				"deviating_from_expected_route": "red",
				"moving_too_slow": "yellow"
			  },
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Following are the Risk elements:

  • delayed_from_scheduled_at: risk element that an order is delayed from the scheduled time of delivery.
  • delayed_from_initial_eta : risk element that an order is delayed beyond the initial ETA communicated to the customer
  • is_offline : risk element that an order is at risk because the device is not sending updates.
  • deviating_from_expected_route : risk element that an order will be at risk because the driver is deviating from the expected route.
  • moving_away_from_destination : risk element that an order will be at risk because the driver is moving away from the destination.
  • in_low_battery : risk element that an order is at risk because the device may shut off before order completion.
  • moving_too_slow : risk element that an order will be at risk because the driver is moving too slowly to fulfill the order.
  • in_outage : risk element that an order is at risk because of a user-driven or software-driven action. eg: turn off GPS, background process killed etc.
NameTypeMandatoryDescription
data.valuestringYesrisk_updated
data.order_handlestringYesUnique handle for the Order
data.route_handlestringYesUnique identifier of the route containing the order
data.driver_handlestringNoUnique identifier of the driver fulfilling the order
data.statusstringYesStatus of the order - ongoing
data.share_urlstringYesContains tracking url of the order to provide real time visibility of driver on route of this order
data.metadataobjectNoMetadata that you have assigned to this order
data.risk_elementsobjectYesOrder at risk state
data.risk_elements.is_offlineobjectNoRisk element evaluating the online/offline status of driver with a value of red or yellow
data.risk_elements.deviating_from_expected_routeobjectNoRisk element evaluating the deviation in route taken by driver against the expected route with a value of red or yellow
data.risk_elements.moving_away_from_destinationobjectNoRisk element evaluating the direction of driver, if he is moving away from destination with a value of red or yellow
data.risk_elements.in_low_batteryobjectNoRisk element evaluating the battery status of the driver's device with a value of red or yellow
data.risk_elements.moving_too_slowobjectNoRisk element evaluating the speed of driver with a value of red or yellow
data.risk_elements.in_outageobjectNoRisk element evaluating the outage status of driver with a value of red or yellow

Route Created Webhook

Route Created Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"created",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"planned",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYescreated
data.route_handlestringYesUnique identifier of the route
data.driver_handlestringNoUnique identifier of the driver fulfilling the route
data.statusstringYesStatus of the route - planned
data.metadataobjectNoMetadata that you have assigned to this route
data.embed_urlstringYesEmbeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders

Route Assigned Webhook

Route Assigned Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"assigned",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"assigned",
			"assigned_at": "2021-01-01T14:00:00.000Z",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesassigned
data.route_handlestringYesUnique identifier of the route
data.driver_handlestringNoUnique identifier of the driver fulfilling the route
data.assigned_attimestampYesTimestamp indicating when the route was assigned
data.statusstringYesStatus of the route - assigned
data.metadataobjectNoMetadata that you have assigned to this route
data.embed_urlstringYesEmbeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders

Route Estimate Generated Webhook

Route Estimate Generated Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"estimate_generated",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"planned",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
      "estimate":{
				"distance": 7382,
				"duration": 1263,
				"start_by": "2021-01-01T14:05:00.000Z"
			  },
			"metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesestimate_generated
data.route_handlestringYesUnique identifier of the route
data.driver_handlestringNoUnique identifier of the driver fulfilling the route
data.statusstringYesStatus of the route - planned
data.metadataobjectNoMetadata that you have assigned to this route
data.embed_urlstringYesEmbeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders
data.estimateobjectYesObject containing the estimate metrics for the route
data.estimate.distanceintYesEstimated total distance in meters to be travelled by the driver to fulfill the orders
data.estimate.durationintYesEstimated total duration in seconds it would take for the driver to fulfill the orders
data.estimate.start_bytimestampYesEstimated start time for the route to ensure all orders are fulfilled within the provided order scheduled times

Route Started Webhook

Route Started Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"started",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"tracking",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
			"metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesstarted
data.route_handlestringYesUnique identifier of the route
data.driver_handlestringNoUnique identifier of the driver fulfilling the route
data.statusstringYesStatus of the route - tracking
data.metadataobjectNoMetadata that you have assigned to this route
data.embed_urlstringYesEmbeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders

Route Completed Webhook

Route Completed Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"completed",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"completed",
			"distance": 6278,
			"duration": 1273,
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
			"metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYescompleted
data.route_handlestringYesUnique identifier of the route
data.driver_handlestringNoUnique identifier of the driver fulfilling the route
data.statusstringYesStatus of the route - completed
data.metadataobjectNoMetadata that you have assigned to this route
data.embed_urlstringYesEmbeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders
data.distanceintYesTotal distance in meters travelled by the driver to fulfill the orders
data.durationintYesTotal duration in seconds it took for the driver to fulfill the orders

Route Updated Webhook

Route Updated Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"updated",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "status":"tracking",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
			"metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]
NameTypeMandatoryDescription
data.valuestringYesupdated
data.route_handlestringYesUnique identifier of the route
data.driver_handlestringNoUnique identifier of the driver fulfilling the route
data.statusstringYesStatus of the route - tracking
data.metadataobjectNoMetadata that you have assigned to this route
data.embed_urlstringYesEmbeddable url of the route to provide real time visibility of driver on route to fulfill the batch of orders

Route Request Version Missing Webhook

Route Request Version Missing Webhook Payload

[
  {
   "created_at":"2021-01-01T14:01:00.000000Z",
   "recorded_at":"2021-01-01T14:00:00.000000Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"request_version_missing",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "driver_handle": "Driver-1",
      "route_version": 3,
      "route_operation": "add_orders",
      "message": "Multiple version exist for route. Specify the latest version in the API",
      "status":"tracking",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
			"metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Deprecated - Location Payload

[
  {
   "created_at":"2019-07-01T20:00:01.247377Z",
   "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
   "recorded_at":"2019-07-01T20:00:00.000000Z",
   "type":"location",
   "data":{
      "accuracy":9.64,
      "geometry":{
         "type":"Point",
         "coordinates":[
            -6.2755,
            57.6398983124
         ]
        },
      "speed":0.0,
      "bearing":313.94
     },
   "version":"2.0.0"
  }
]
NameTypeDescription
data.geometryobjectLocation in GeoJSON format
data.geometry.typestringAs of right now, only Point is supported
data.geometry.coordinatesarrayArray of longitude, latitude and (optional) altitude (in m)
data.accuracyfloat(optional) accuracy in m
data.bearingfloat(optional) bearing in degrees starting at due north and continuing clockwise around the compass
data.speedfloat(optional) speed in m/s