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

Name	Type	Description
device_id	string	Unique device identifier, case sensitive (Present where the webhook originates from a device)
created_at	string	ISO 8601 date and time when webhook was sent (server timestamp)
recorded_at	string	ISO 8601 date and time when event was recorded (client timestamp). Not available for trip webhooks (e.g. start and completion)
type	string	Type 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.
data	object	Data corresponding to the type. See detailed description below.
location	object	GeoJSON object with `type` and `coordinates`. Provided as context to trip delay webhooks only
version	string	Version 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:

Feature	Type	Description
Locations	location	Location stream
Device Status	device_status	Device status changes (active, inactive, disconnected and activity changes)
Battery	battery	Battery changes (low, normal and charging)
Trips	trip	Trip start, destination arrival, destination exit, trip delays, and trip completion events
Geotags	geotag	Geotags stream
Orders	order	Orders lifecycle changes like order start, completion, cancellation, eta change etc

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

Name	Type	Description
data.value	string	Battery status. Values include `low`, `normal` and `charging`
location	object	Location in GeoJSON format
location.type	string	As of right now, only `Point` is supported
location.coordinates	array	Array 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"
  }
]

Name	Type	Description
data.value	string	Battery status. Values include `low`, `normal` and `charging`
data.battery_percent	int	Battery 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 worker 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"
  }
]

Name	Type	Description
data.value	string	Time offset from the current time versus time set by the app user.
data.user_time	object	Time 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.

Name	Type	Description
data.value	string	One of: `created`, `destination_arrival`, `destination_exit`, `delayed`, `first_eta`, `eta_change` or `completed`
data.trip_id	string	Unique identifier of the trip, case sensitive
data.trip_metadata	Object	Metadata that you have assigned to this trip (optional)
data.arrive_at	string	Timestamp with new arrived date, only available if `value` is `delayed`
data.remaining_duration	int	Time remaining (in seconds) as per ETA calculations, only available if `value` is `eta_change` or `first_eta`
data.remaining_distance	int	Distance remaining (in meters) as per ETA calculations, only available if `value` is `eta_change` or `first_eta`
data.destination_id	string	Unique identifier of the trip destination, case sensitive (Only available for trips with multiple orders)
data.destination_metadata	Object	Metadata that you have assigned to the trip destination (Only available for trips with multiple orders)
data.duration	int	Duration of trip (in seconds), only available if `value` is `completed`
data.distance	int	Distance travelled during trip (in meters), only available if `value` is `completed`
data.duration_at_destination	int	Duration 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.

Name	Type	Description
data.value	string	Label 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.

Name	Type	Description
data.value	string	Label 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.

Name	Type	Description
data.value	string	Label 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",
    "order_status": "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 ]
    },
    "worker_handle": "James"
  },
  "device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
  "type": "geotag",
  "version": "3.0.0"
  }
]

Name	Type	Description
data.order_handle	string	Unique identifier for an order
data.order_status	string	Label identifying a segment of order fulfillment
data.worker_handle	string	Unique identifier for a worker
data.metadata	Object	Metadata that you have assigned to this geotag (optional)
data.location	Object	Location in GeoJSON format
data.expected_location	Object	Location in GeoJSON format
data.location.type	string	As of right now, only `Point` is supported
data.location.coordinates	array	Array of `longitude` `latitude` and (optional) `altitude` (in m)
data.expected_location.type	string	As of right now, only `Point` is supported
data.expected_location.coordinates	array	Array of `longitude` `latitude` and (optional) `altitude` (in m)
data.deviation	int	Deviation between expected location and actual location
data.distance	int	Distance travelled since last geotag
data.duration	int	Time 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"
  }
]

Name	Type	Description
device_id	string	Unique device identifier, case sensitive
driver_handle	string	Unique identifier for a worker
data.arrival	object	Object representing details about the geofence arrival
data.arrival.location	object	Location object that triggered geofence arrival
data.arrival.location.type	string	As of right now, only `Point` is supported
data.arrival.location.coordinates	array	Array of `longitude`, `latitude` and (optional) elevation
data.arrival.recorded_at	string	ISO 8601 date when the location triggering arrival was recorded
data.exit	object	Object representing details about the geofence exit. Does not exist when the user is still inside the geofence. {optional}
data.exit.location	object	Location 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.type	string	As of right now, only `Point` is supported
data.exit.location.coordinates	array	Array of `longitude`, `latitude` and (optional) elevation
data.exit.recorded_at	string	ISO 8601 date when the event triggering exit was recorded
data.duration	int	Duration of the visit in [seconds]
data.geometry	Object	Geofence geometry of the geofence creating this marker
data.marker_id	String	Unique identifier for this geofence marker
data.place_handle	String	Unique 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_to	object	Object describing the route since last geofence marker (optional)
data.route_to.distance	int	Distance travelled since last geofence marker or start of tracking session in [meters]
data.route_to.duration	int	Duration since last geofence marker or start of tracking session in [seconds]
data.route_to.idle_time	int	Duration at stops since last geofence marker or start of tracking session in [seconds]
data.route_to.started_at	String	ISO 8601 Date and time when route_to calculation started
data.value	String	'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*
location	object	Deprecated 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",
   "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`planning_started`
data.planning_sequence_number	integer	Yes	Sequence Number of the plan for this specific plan ID
data.plan_id	string	Yes	Unique identifier of the plan which is getting planned
data.planning_started_reason	string	Yes	Trigger reason for this specific planning
data.started_at	string	Yes	Timestamp at which plan was started
data.ops_group_handle	string	Yes	Ops 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",
   "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`planning_completed`
data.planning_sequence_number	integer	Yes	Sequence Number of the plan for this specific plan ID
data.plan_id	string	Yes	Unique identifier of the plan which is getting planned
data.num_orders	integer	Yes	Number of Orders planned
data.num_orders	integer	Yes	Number of Orders planned
data.num_routes	integer	Yes	Number of Routes planned
data.num_unplanned_orders	integer	Yes	Number of Orders which could not be planned
data.started_at	string	Yes	Timestamp at which plan was started
data.completed_at	string	Yes	Timestamp at which plan was completed
data.route_handles_created	string	Yes	Route handles which got created in this planning instance
data.route_handles_modified	string	Yes	Route handles which got modified in this planning instance
data.ops_group_handle	string	Yes	Ops 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",
   "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`planning_failed`
data.planning_sequence_number	integer	Yes	Sequence Number of the plan for this specific plan ID
data.plan_id	string	Yes	Unique identifier of the plan which is getting planned
data.num_orders	integer	Yes	Number of Orders planned
data.failure_reason	string	Yes	Faiure reason for Planning
data.num_unplanned_orders	integer	Yes	Number of Orders which could not be planned
data.started_at	string	Yes	Timestamp at which plan was started
data.ops_group_handle	string	Yes	Ops 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"started",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`started`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata 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",
   "worker_handle": "Worker-1",
   "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",
      "assign_source": "automated",
      "status":"assigned",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`assigned`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.assigned_at	timestamp	Yes	Timestamp indicating when the order was assigned
data.status	string	Yes	Status of the order - `assigned`
data.assign_source	enum	No	Enumerated string to distinguish how did the order get assigned, either `manual` or `automated`
data.metadata	object	No	Metadata 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"first_eta",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "remaining_distance": 2582,
      "remaining_duration": 410,
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`first_eta`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.remaining_distance	int	Yes	Distance remaining in meters
data.remaining_duration	int	Yes	Time 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"eta_change",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "remaining_distance": 2382,
      "remaining_duration": 359,
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "change_reason": "position_update",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`eta_change`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.change_reason	string	Yes	contains the reason of why eta changed, enumerated as one of `position_update`- ETA recalculated from worker's new position `route_change` - Route to destination was recalculated `traffic_update` - Real-time traffic conditions changed Note- `traffic_update` can also lead to a route recalculation
data.metadata	object	No	Metadata that you have assigned to this order
data.remaining_distance	int	Yes	Distance remaining in meters
data.remaining_duration	int	Yes	Time remaining to reach destination as per current location in seconds
data.earliest_possible_arrival_time	string	No	Earliest arrival time assuming free-flowing traffic from the current known location of the worker

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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"delayed",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`delayed`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.arrive_at	timestamp	Yes	Timestamp indicating the new expected arrival time
data.scheduled_at	timestamp	No	Timestamp indicating the provided scheduled time for order fulfillment
data.initial_eta	timestamp	No	Timestamp 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"n_minutes_away",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`n_minutes_away`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.remaining_distance	int	Yes	Distance remaining in meters
data.remaining_duration	int	Yes	Time remaining to reach destination as per current location in seconds
data.remaining_minutes	int	Yes	Time 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"disabled",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status":"disabled",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`disabled`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `disabled`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"enabled",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`enabled`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"updated",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`updated`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"arrived",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`arrived`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.place_handle	string	No	Unique 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.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.scheduled_at	timestamp	No	Timestamp indicating the provided scheduled time for order fulfilment
data.initial_eta	timestamp	No	Timestamp indicating the initial expected arrival time
data.arrival	object	Yes	Contains 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"exited",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`exited`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.place_handle	string	No	Unique 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.reason	string	Yes	One of the following: `deleted`: The corresponding `arrived` webhook was deleted due to updated information. `geofence_deleted`: The geofence was deleted. `location`: The worker exited the location. `outage`: A user action, such as denying permission, caused tracking to stop. This is treated as a geofence exit.
data.status	string	Yes	Status of the order - `ongoing`, `completed`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.exit	object	Yes	Contains location and recorded_at timestamp of the exit from the order destination location. Location can be null 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"completed",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`completed`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `completed`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.distance	int	Yes	Total distance travelled to fulfill the order. In case of no location data stream from the worker’s device during the shift, distance will be set to null.
data.duration	int	Yes	Total time in seconds since order start. Can also be null in cases when there is no data sent from the worker’s device.
data.deviation	int	No	Deviation between order destination location and actual location where the order is completed
data.actual_service_time	int	No	Total time spent by worker 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"cancelled",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "distance":1834,
      "duration":408,
      "status":"cancelled",
      "share_url":"https://trck.at/vr1RNLq",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`cancelled`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Can be null	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `cancelled`
data.share_url	string	Can be null	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.distance	int	Can be null	Total distance travelled to fulfill the order. In case of no location data stream from the worker’s device during the shift, distance will be set to null.
data.duration	int	Can be null	Total time in seconds since order start. Can also be null in cases when there is no data sent from the worker’s device.

Orders Device Switched Payload

Order Device Switched 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"device_switched",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "previous_device_id":"00112233-4455-6677-8899-AABBCCDD8743",
      "new_device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        }
     },
   "version":"3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`device_switched`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	No	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`\| `assigned`
data.share_url	string	No	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.previous_device_id	string	No	Unique Identifier of the device to which order was previously connected
data.new_device_id	string	Yes	Unique Identifier of the device to which order is switched to
data.metadata	object	No	Metadata that you have assigned to this order

Orders Geofence Checked Payload

Orders Geofence Checked Payload

[
   {
      "created_at":"2021-01-01T14:01:00.000000Z",
      "recorded_at":"2021-01-01T14:00:00.000000Z",
      "device_id":"00112233-4455-6677-8899-AABBCCDDEEFF",
      "worker_handle":"Worker-1",
      "account_id":"6784e919-7168-4f61-b686-2020f547637f",
      "type":"order",
      "data":{
         "is_inside":true,
         "metadata":{
            "storeId":"123490809808",
            "customerName":"Andrew"
         },
         "order_handle":"DGC127092",
         "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
         "share_url":"https://trck.at/DqaybldkqY",
         "status":"ongoing",
         "value":"on_device_geofence_checked",
         "location_accuracy":20
      },
      "version":"3.0.0",
      "location":{
         "coordinates":[
            77.643271,
            12.94964
         ],
         "type":"Point"
      }
   }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`on_device_geofence_checked`
data.order_handle	string	Yes	Unique handle for the Order
data.is_inside	boolean	Yes	Indication if the checkin was done inside or outside the order destination geofence; null if worker was in outage during check
data.outages	array	No	if worker was in an outage during the check, this is set with details about the outage
data.outages[].outage_category	enum	Yes	adversarial, behavioural, sporadic, os, reachability
data.outages[].outage_label	string	Yes
data.outages[].outage_code	string	Yes
data.outages[].outage_description	string	Yes
data.location_accuracy	integer	No	Accuracy of the location used to check whether it is inside order destination geofence or not
data.route_handle	string	No	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`\| `assigned`
data.share_url	string	No	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order

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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"order",
   "data":{
      "value":"risk_updated",
      "order_handle":"DGC127092",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status":"ongoing",
      "share_url":"https://trck.at/vr1RNLq",
      "risks":{
        "deviating_from_expected_route":{
          "intensity_label": "red",
          "intensity_value": 0.85,
          "previous_intensity_label": "yellow"
        },
        "moving_too_slow":{
          "intensity_label": "yellow",
          "intensity_value": 0.45,
          "previous_intensity_label": "green"
        }
      },
      "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 worker is deviating from the expected route.
moving_away_from_destination : risk element that an order will be at risk because the worker 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 worker is moving too slowly to fulfil 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.

Name	Type	Mandatory	Description
data.value	string	Yes	`risk_updated`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.risks	object	Yes	Order at risk state
data.risks.is_offline	object	No	Risk element evaluating the online/offline status of worker with a value of `red` or `yellow`
data.risks.deviating_from_expected_route	object	No	Risk element evaluating the deviation in route taken by worker against the expected route with a value of `red` or `yellow`
data.risks.moving_away_from_destination	object	No	Risk element evaluating the direction of worker, if he is moving away from destination with a value of `red` or `yellow`
data.risks.in_low_battery	object	No	Risk element evaluating the battery status of the worker's device with a value of `red` or `yellow`
data.risks.moving_too_slow	object	No	Risk element evaluating the speed of worker with a value of `red` or `yellow`
data.risks.in_outage	object	No	Risk element evaluating the outage status of worker with a value of `red` or `yellow`
data.risks..intensity_label	string	Yes	Risk elements intensity, can be `red`, `yellow` or `green`. `green` means no risk and `red` means at risk.
data.risks..intensity_value	number	Yes	Number between 0 and 1 representing the severity of risk where 0 is no risk.
data.risks..previous_intensity_label	string	No	Risk elements previously calculated intensity, useful in understanding which elements changed in this webhook

Order Billing Details Updated Webhook

Order Billing Details 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",
   "worker_handle": "Worker-1",
   "account_id": "6784e919-7168-4f61-b686-2020f547637f",
   "type": "order",
   "data": {
      "value": "billing_details_updated",
      "order_handle": "DGC127092",
      "route_handle": "4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "status": "ongoing",
      "share_url": "https://trck.at/vr1RNLq",
      "billing_details": {
         "billable_hours": 10,
         "travel_time": 10,
         "service_time": 10,
         "breaks": [
            {
               "end_time": "2021-01-01T14:30:00.000Z",
               "id": "28315a00-2ee9-4477-bd77-37dc096a8f49",
               "start_time": "2021-01-01T14:20:00.000Z"
            }
         ]
      },
      "metadata": {
         "storeId": "123490809808",
         "customerName": "Andrew"
      }
   },
   "version": "3.0.0"
}

Name	Type	Mandatory	Description
data.value	string	Yes	`billing_details_updated`
data.order_handle	string	Yes	Unique handle for the Order
data.route_handle	string	Yes	Unique identifier of the route containing the order
data.status	string	Yes	Status of the order - `ongoing`
data.share_url	string	Yes	Contains tracking url of the order to provide real time visibility of worker on route of this order
data.metadata	object	No	Metadata that you have assigned to this order
data.billing_details	object	Yes	Billing Details
data.billing_details.billable_hours	float	No	Total billable hours computed for the order.
data.billing_details.travel_time	integer	No	Time spent traveling to the order destination.
data.billing_details.service_time	integer	No	Time spent servicing the order.
data.billing_details.breaks	object	No	List of breaks observed during the order.
data.billing_details.breaks.id	string	Unique identifier for the break
data.billing_details.breaks.start_time	string	Timestamp indicating the start of break
data.billing_details.breaks.end_time	string	Timestamp indicating the end of break

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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"created",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`created`
data.route_handle	string	Yes	Unique identifier of the route
data.status	string	Yes	Status of the route - `planned`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"assigned",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`assigned`
data.route_handle	string	Yes	Unique identifier of the route
data.assigned_at	timestamp	Yes	Timestamp indicating when the route was assigned
data.status	string	Yes	Status of the route - `assigned`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker on route to fulfil 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"estimate_generated",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`estimate_generated`
data.route_handle	string	Yes	Unique identifier of the route
data.status	string	Yes	Status of the route - `planned`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker on route to fulfil the batch of orders
data.estimate	object	Yes	Object containing the estimate metrics for the route
data.estimate.distance	int	Yes	Estimated total distance in meters to be travelled by the worker to fulfil the orders
data.estimate.duration	int	Yes	Estimated total duration in seconds it would take for the worker to fulfil the orders
data.estimate.start_by	timestamp	Yes	Estimated 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"started",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`started`
data.route_handle	string	Yes	Unique identifier of the route
data.status	string	Yes	Status of the route - `tracking`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker on route to fulfil 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"completed",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`completed`
data.route_handle	string	Yes	Unique identifier of the route
data.status	string	Yes	Status of the route - `completed`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker on route to fulfil the batch of orders
data.distance	int	Yes	Total distance in meters travelled by the worker to fulfill the orders
data.duration	int	Yes	Total duration in seconds it took for the worker 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"updated",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`updated`
data.route_handle	string	Yes	Unique identifier of the route
data.status	string	Yes	Status of the route - `tracking`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker on route to fulfil 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",
   "worker_handle": "Worker-1",
   "account_id":"6784e919-7168-4f61-b686-2020f547637f",
   "type":"route",
   "data":{
      "value":"request_version_missing",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "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"
  }
]

Route Candidate Device Updated 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",
    "worker_handle": "Worker-1",
    "account_id": "6784e919-7168-4f61-b686-2020f547637f",
    "type": "route",
    "data": {
      "value":"candidate_devices_updated",
      "route_handle":"4359cc65-90dd-4b2b-875b-26e6d2eba11d",
      "embed_url":"https://embed.hypertrack.com/trips/4359cc65-90dd-4b2b-875b-26e6d2eba11d?publishable_key=lujVNBunxFFHBQ2gk980UqQ3KQemmKRsqlATo4nes959pKEo9nAqxv60Sk1r1HR_KSpdZ0feR4FLajKuw",
      "status":"tracking",
      "metadata":{
         "storeId":"123490809808",
         "customerName":"Andrew"
        },
      "candidate_devices": [
        "00112233-4455-6677-8899-AABBCCDDEEFF",
        "33221100-4455-6677-8899-AABBCCDDEEFF"
      ]
    },
    "version": "3.0.0"
}

Name	Type	Mandatory	Description
data.value	string	Yes	`updated`
data.route_handle	string	Yes	Unique identifier of the route
data.status	string	Yes	Status of the route - `tracking`
data.metadata	object	No	Metadata that you have assigned to this route
data.embed_url	string	Yes	Embeddable url of the route to provide real time visibility of worker on route to fulfill the batch of orders
data.candidate_devices	array	Yes	List of candidate devices available for this route. Updated list after addition/removal of a candidate device.

Worker Webhooks

Webhooks are sent to highlight significant events during a worker's shift.
Sample webhook payloads for each salient event can be found below.

Tracking Started Webhook

This webhook is sent upon reception of the first location post tracking start action.

Worker Tracking Started Webhook Payload

[
  {
    "type": "worker",
    "device_id": "AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "worker_handle": "worker-shashwat",
    "data": {
      "address": "Princeville, Embassy Golf Links Road, Embassy GolfLinks Business Park, Domlur, Bengaluru, Bangalore East, Bengaluru Urban, Karnataka, 560001, India",
      "value": "tracking_started",
      "location_recorded_at": "2024-08-30T07:52:12.042Z",
    },
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "created_at": "2024-08-30T07:52:17.840332Z",
    "recorded_at": "2024-08-30T07:52:12.042450168Z",
    "version": "3.0.0"
  }
]

Name	Type	Mandatory	Description
worker_handle	string	Yes	Handle of the worker.
location	object	Yes	GeoJSON object with `type` and `coordinates`.
data.value	string	Yes	`tracking_started`
data.location_recorded_at	string	Yes	Timestamp of the location reading
data.address	string	Yes	Human friendly address of the location

Work Status Updated Webhook

This webhook is sent whenever a worker’s work status changes. For example, it is triggered when the tracking or available status switches from false to true (or true to false). It contains details about the worker, the device, and the updated status.

{
  "device_id": "AB930CCD-50A9-4ECA-8758-D7CB09058606",
  "recorded_at": "2024-08-30T07:52:12.042450168Z",
  "type": "worker",
  "version": "3.0.0",
  "worker_handle": "worker-shashwat",
  "data": {
    "value": "work_status_updated",
    "work_status": {
      "tracking": true,
      "available": true
    }
  }
}

Name	Type	Mandatory	Description
data.value	string	Yes	`work_status_updated`
data.work_status.available	enum	Yes	Whether the worker is available
data.work_status.tracking	string	Yes	Whether the worker is tracking
worker_handle	string	Yes	Unique handle of the worker.
device_id	string	No	Unique Identifier of the device which is being used by worker

Outage Started Webhook

This webhook is sent when a worker gets into an outage.

[
  {
    "type": "worker",
    "device_id":"AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "data": {
      "value": "outage_started",
      "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."
    },
    "recorded_at": "2024-11-28T12:45:00.000Z",
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "worker_handle": "ram@123",
    "version": "3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`outage_started`
data.outage_category	enum	Yes	adversarial, behavioural, sporadic, os, reachability
data.outage_label	string	Yes
data.outage_code	string	Yes
data.outage_description	string	Yes
worker_handle	string	Yes	Unique handle of the worker.
device_id	string	Yes	Unique Identifier of the device which is being used by worker
location	GeoJSON	No	Location in [GeoJSON format] where outage is started

Outage Ended Webhook

This webhook is sent when a worker's outage gets resolved and started tracking

[
  {
    "type": "worker",
    "device_id":"AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "data": {
      "value": "outage_ended",
      "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."
    },
    "recorded_at": "2024-11-28T12:45:00.000Z",
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "worker_handle": "ram@123",
    "version": "3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`outage_ended`
data.outage_category	enum	Yes	adversarial, behavioural, sporadic, os, reachability
data.outage_label	string	Yes
data.outage_code	string	Yes
data.outage_description	string	Yes
worker_handle	string	Yes	Unique Handle of the worker.
device_id	string	Yes	Unique Identifier of the device which is being used by worker
location	GeoJSON	Yes	Location in [GeoJSON format] where outage is resolved

Device Disconnected Webhook

This webhook is sent when a worker's current device gets disconnected from internet during a tracking session

[
  {
    "type": "worker",
    "device_id":"AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "data": {
      "value": "device_disconnected"
    },
    "recorded_at": "2024-11-28T12:45:00.000Z",
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "worker_handle": "ram@123",
    "version": "3.0.0"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`device_disconnected`
worker_handle	string	Yes	Unique Handle of the worker.
device_id	string	Yes	Unique Identifier of the device which got disconnected
location	GeoJSON	No	Location in [GeoJSON format] where device got disconnected

Device Connected Webhook

This webhook is sent when a worker's device network connectivity is restored after being disconnected during a tracking session

[
  {
    "type": "worker",
    "device_id":"AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "data": {
      "value": "device_connected"
    },
    "recorded_at": "2024-11-28T12:45:00.000Z",
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "worker_handle": "ram@123",
    "version": "3.0.0" 
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`device_connected`
worker_handle	string	Yes	Unique Handle of the worker.
device_id	string	Yes	Unique Identifier of the device which connected
location	GeoJSON	No	Location in [GeoJSON format] where device connected

Device Linked Webhook

This webhook is sent when a worker is linked to a device different from previously linked device

[
  {
    "type": "worker",
    "device_id":"AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "data": {
      "value": "device_linked"
    },
    "recorded_at": "2024-11-28T12:45:00.000Z",
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "worker_handle": "ram@123"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`device_linked`
worker_handle	string	Yes	Unique Handle of the worker.
device_id	string	Yes	Unique Identifier of the device which is linked with the worker
location	GeoJSON	No	Location in [GeoJSON format] where device connected

Device Unlinked Webhook

This webhook is sent when a worker is unlinked from a device

[
  {
    "type": "worker",
    "device_id":"AB930CCD-50A9-4ECA-8758-D7CB09058606",
    "data": {
      "value": "device_unlinked"
    },
    "recorded_at": "2024-11-28T12:45:00.000Z",
    "location": {
        "type": "Point",
        "coordinates": [
          77.643271,
          12.94964
        ]
    },
    "worker_handle": "ram@123"
  }
]

Name	Type	Mandatory	Description
data.value	string	Yes	`device_unlinked`
worker_handle	string	Yes	Unique Handle of the worker.
device_id	string	Yes	Unique Identifier of the device which got unlinked from the worker
location	GeoJSON	No	Location in [GeoJSON format] where device connected

Deprecated

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":"alex+test123@hypertrack.com"
   },
   "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"
}

Name	Type	Description
data.value	string	Device status. One of `active`, `inactive` or `disconnected`. Please read here to understand how HyperTrack tracks device status.
data.activity	string	For active devices only, can be one `walk`,`drive`, or `stop`
data.outage_category	enum	Yes	adversarial, behavioural, sporadic, os, reachability
data.outage_label	string	Yes
data.outage_code	string	Yes
data.outage_description	string	Yes
data.start	object	Available in case of `data.value` is `active` and an activity has been completed, Gives information of when and where the activity started
data.end	object	Available in case of `data.value` is `active` and an activity has been completed, Gives information of when and where the activity ended
data.distance	int	Available in case of `data.value` is `active` and an activity has been completed
data.duration	int	Available in case of `data.value` is `active` and an activity has been completed
location	object	Location in GeoJSON format
location.type	string	As of right now, only `Point` is supported
location.coordinates	array	Array of `longitude` `latitude` and (optional) `altitude` (in m)

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

Name	Type	Description
data.geometry	object	Location in GeoJSON format
data.geometry.type	string	As of right now, only `Point` is supported
data.geometry.coordinates	array	Array of `longitude`, `latitude` and (optional) `altitude` (in m)
data.accuracy	float	(optional) accuracy in m
data.bearing	float	(optional) bearing in degrees starting at due north and continuing clockwise around the compass
data.speed	float	(optional) speed in m/s