Hypertrack, Inc

Stream locations and markers via webhooks

Use webhooks to ingest live location as well as activity, outage, trip, geotag, and geofence markers generated by your devices from HyperTrack to your server end point. This can allow you to implement real-time application workflows on your server.

Use status updates and markers to power your application workflows

Your webhook integration with HyperTrack can empower you to handle application workflows on your server in real-time as soon as your app user's devices generate location data. You can ingest the following webhook updates posted to your server:

Activity transitions

The device is actively sending updates. In that case, the device_status.data object is provided with an activity property. It can be one of stop, walk, or drive.

note

Run and cycle activities are purposefully removed because fewer businesses cared about it, and inaccurate classification obfuscated walks and drives. We are working on adding public transit detection, including trains, ferries and buses.

Understanding device status

The device_status object has properties that are conditional to device_status.value.

It can be one of the following: active, inactive or disconnected. See here for a detailed description.

Active device status includes an activity
"device_status": {
"data": {
"recorded_at": "2019-07-30T01:38:45.610000Z",
"activity": "stop"
},
"value": "active"
}

Device status changes includes a device becoming active, inactive/disconnected and activity (stop, walk or drive) transitions

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "device_status",
"data": {
"value": "active",
"activity": "walk",
"start":{
"location": {
"geometry": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
}
},
"recorded_at": "2019-07-01T20:00:00.000000Z"
},
"end":{
"location": {
"geometry": {
"type": "Point",
"coordinates": [-6.2765, 57.6388983, 128]
}
},
"recorded_at": "2019-07-01T20:10:00.000000Z"
},
"distance": 563,
"duration": 600
},
"location": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"version": "2.0.0"
}

Device status provides update about the device. The value can be active, inactive and disconnected. Please read here to understand how HyperTrack tracks device status.

Mobile devices send health data through the Mobile SDKs. The data is showing tracking outages and resumptions. Health data is available for outage events when an outage affects location data. This data is sent with a low frequency (based on device activity).

When the device is active, we include the activity when available. Mobile phones use a variety of sensors combined with location data to intelligently identify phone users’ activity. Activity transitions are sent with a medium frequency (similar to summary events).

HyperTrack supports 3 types of activity transitions: walk, drive, and stop.

For your convenience, we provide you a set of free-to-use SVG icons to display activities in your application.

Outage notifications

Inactive device status

Inactive device status includes a reason
"device_status": {
"data": {
"recorded_at": "2019-09-03T16:39:35.326000Z",
"reason": "tracking_stopped"
},
"value": "inactive"
}

The device is not sending location updates and in that case, the device_status.data object is contains reason property`. These reasons can be one of the following below:

  • airplane_mode_detected
  • location_permissions_denied
  • location_services_disabled
  • low_battery
  • motion_activity_permissions_denied
  • motion_activity_services_disabled
  • motion_activity_services_unavailable
  • push_token_missing_to_start_tracking
  • tracking_stopped
  • tracking_service_terminated
  • deleted
  • uninstalled
  • location_unavailable
  • location_unavailable_battery_saver
  • location_unavailable_provisional_authorization
  • sdk_killed_low_memory
  • sdk_killed_by_user
  • sdk_killed_by_app_update
  • sdk_killed_by_permissions_activity
  • sdk_killed_by_permissions_location
  • sdk_killed_by_os_update
  • sdk_killed_by_os_reboot
  • sdk_killed_by_low_power
  • storage_unavailable
  • network_limit_reached
  • location_permission_asked_in_background
  • location_permission_restricted
  • motion_activity_permission_not_determined
  • motion_activity_permission_asked_in_background
  • location_permission_not_determined

Note that this is an embeddable dashboard view that you can implement in minutes for your ops managers as explained in this guide.

Disconnected device status

Disconnected device status does not have any data
"device_status": {
"data": {},
"value": "disconnected"
}

Connection with the device was lost unexpectedly (no data received for over an hour). In that case, the device_status.data object is empty.

Geotags

Geotags are generated when your app users take action in the app as described in the track work day with geotags guide as well as in track actual distance between geotags guide.

Integrate geotags in real-time with your app backend via webhooks

If your app business workflow requires real-time integration of app user's notes as they take place, please review an example payload as shown below.

You can see that not only you get back payload data your app user generated from the mobile app, but also route_to data which contain distance in meters, duration in seconds, start_location from the previous geotag event for which distance and duration is generated, as well as recorded_at timestamp which captures the time this app event was received from your user's app.

Plus, you get location that HyperTrack captures for you when your app user generates a note in the app.

{
"created_at": "2019-07-01T14:01:00.000000Z",
"recorded_at": "2019-07-01T14:00:00.000000Z",
"data": {
"metadata": {
"product_id": "Kent Ace",
"action": "sold",
"quantity": 5,
"customer_name": "Amit K"
},
"route_to":{
"distance": 238,
"duration": 63,
"start_location": {
"geometry": {
"coordinates": [
-6.271,
57.6398983
],
"type": "Point"
},
"recorded_at": "2019-07-01T13:52:08.213000Z"
}
}
},
"location": {
"type": "Point",
"coordinates": [
-6.2755,
57.6398983
]
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "geotag",
"version": "2.0.0"
}

Get geotag distances in real-time via webhooks

Please review an example payload as shown below.

You can see that not only you get back payload data your app user generated from the mobile app, but also route_to data which contain distance in meters, duration in seconds, start_location from the previous app event for which distance and duration is generated, as well as recorded_at timestamp which captures the time this app event was received from your mobile app.

Lastly, but not least importantly, you get location that HyperTrack captures for you when your app user generates an app event.

{
"created_at": "2019-07-01T14:01:00.000000Z",
"recorded_at": "2019-07-01T14:00:00.000000Z",
"data": {
"metadata": {
"Route type": "Car",
"Station Id": "1BCX",
"Package Id": "1WUXZ1393",
"Route Id": "2248311",
"Action Type": "Reached Doorstep"
},
"route_to":{
"distance": 238,
"duration": 63,
"start_location": {
"geometry": {
"coordinates": [
-6.271,
57.6398983
],
"type": "Point"
},
"recorded_at": "2019-07-01T13:52:08.213000Z"
}
}
},
"location": {
"type": "Point",
"coordinates": [
-6.2755,
57.6398983
]
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "geotag",
"version": "2.0.0"
}

Trip status

In your business workflow, you may need to take actions depending on the status of the trip you created for your app user. HyperTrack provides real-time updates for your app that deliver to you important events associated with your trip.

Trip events are posted whenever a trip is started, a specified device enters or exits the destination, a trip with a scheduled arrival is estimated to be delayed, and when a trip is completed. Events provide the device triggering the event, the trip, event type (create, destination enter, destination exit, delay, or completion), and trip metadata defined during start.

Currently, HyperTrack will send notifications triggered by:

  • Trip start: For every new trip, start events are posted.
  • Destination arrival: Trips destination arrival events are posted when devices enter a specified destination.
  • Destination exit: Same as arrival events, but posted when devices exit the specified destination.
  • ETA changes: As trip progresses it provides you real-time ETA changes
  • Trip delays:Trip delay events are posed for trips with a scheduled arrival time. Delay events are send as soon as the estimated time of arrival is past the scheduled time.
  • Trip completion: For every completed trip, completion events are posted.

All trip updates will include the update type, created_at, device_id, trip_id and trip_metadata at the very least.

It is up to you to decide how to utilize trip updates. To give you an idea, the following can be done:

  • complete trips based on custom logic
  • update database records of trips
  • send mobile device notifications
  • update real-time views and maps
  • start custom processes (training of AI models, send custom emails, etc)

Trigger notifications based on trip activity

A common use case is to leverage trip events to trigger contextual, location-aware notifications in web or native applications. To make these types of notifications possible, you should maintain a list of devices (users), a list of trips, and notification templates for trips events (start, destination enter/exit, completion) to be used as notification message.

It is suggested to leverage device metadata that can be set either through mobile SDKs or through Devices API in combination with trips metadata to establish all relevant information in order to send highly contextualized notifications.

More context is provided based on the update type. Please take a look at the trip webhooks references for more details.

Trip start

Please see an example for the trip start webhook payload. Once the trip is created, you may be able to get Trips API to receive trip estimate and expected route to the destination.

Webhook: Trip created payload
{
"created_at": "2019-07-01T14:00:00.0000Z",
"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"
}

Trip destination arrival

The payload below is an example of the trip destination arrival, as denoted by destination_arrival value field inside data object.

Webhook: Trip destination arrival payload
{
"created_at": "2019-07-01T14:00:00.000Z",
"data": {
"value": "destination_arrival",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" },
"arrival": {
"location": {
"coordinates": [
-122.399701,
37.794227
],
"type": "Point"
},
"recorded_at": "2020-10-10T10:10:10.101Z"
}
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0",
"location": {
"type": "Point",
"coordinates": [-122.399701, 37.794227, 1.12]
},
"recorded_at": "2020-10-10T10:10:20.101Z"
}

Trip destination exit

The payload below is an example of the trip destination exit, as denoted by destination_exit value field inside data object. The data object has the arrival/exit locations and the duration the user stayed at the destination. Note exit location may be empty when the marker was closed due to an outage event.

Webhook: Trip destination arrival payload
{
"created_at": "2019-07-01T14:00:00.000Z",
"data": {
"value": "destination_exit",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" },
"arrival": {
"location": {
"coordinates": [
-122.399701,
37.794227
],
"type": "Point"
},
"recorded_at": "2020-10-10T10:10:10.101Z"
},
"exit": {
"location": {
"coordinates": [
-122.399701,
37.794227
],
"type": "Point"
},
"recorded_at": "2020-10-10T10:20:10.101Z"
},
"duration": 10
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0",
"location": {
"type": "Point",
"coordinates": [-122.399701, 37.794227, 1.12]
},
"recorded_at": "2020-10-10T10:10:20.101Z"
}

Trip ETA change

In a business operations workflow, you may have more than one trip with destination and ETA scheduled for today for a given app user. For example, your app user may be a service technician visiting multiple sites for the day or grocery delivery driver who has a number of drop off locations to visit.

To help understand which trip is most relevant to your customer as your app user is on the route, HyperTrack provides an ETA change via a new webhook for your ongoing trips.

This webhook payload has eta_change inside its value field. You will get this real-time webhook update for all of your trips with destination each time ETA is updated.

The payload below is an example of a trip ETA change, as denoted by remaining_duration and remaining_distance inside data object.

You may be able to use these values to determine when to start notifying your customers and also share real-time locations of your service workers.

Webhook: Trip ETA change payload
{
"created_at": "2020-04-20T10:37:04.378Z",
"type": "trip",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"data":{
"value": "eta_change",
"trip_id": "0c607e25-7e65-45d4-84c7-ba4586c8d580",
"trip_metadata":{
"phonenumber": "14150000000",
"name": "Emily N",
"amount": "0",
"deliveryId": "ADSNXYZ_FC1",
"affiliation": "flooring_carpet",
"branch": "flooring_carpet"
},
"remaining_duration": 935,
"remaining_distance": 7863
},
"version": "2.0.0",
"location": {
"coordinates" :[
36.795995,
-1.2751567
],
"type": "Point"
},
"recorded_at": "2020-04-20T10:36:04.378Z"
}

Trip delay

As explained below you may specify when your app user is expected to reach a destination for your scheduled trip. In case if there is a delay, you will get a webhook update with this payload below. Note that value inside data object is delayed and arrive_at shows the new expected arrival time for your app user.

If the trip gets delayed further, you will receive additional updates via this trip delay webhook until the trip is completed.

Webhook: Trip destination arrival payload
{
"created_at": "2019-07-01T14:00:00.000Z",
"data": {
"value": "delayed",
"arrive_at": "2019-07-02T01:00:00.000Z",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" }
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0",
"location": {
"coordinates" :[
36.795995,
-1.2751567
],
"type": "Point"
},
"recorded_at": "2019-07-01T13:59:00.0000",
}

Trip completion

When the trip is completed, you will receive the trip completion webhook. Key metrics such as distance or duration_at_destination is part of the payload.

Webhook: Trip completed payload
{
"created_at": "2020-10-10T12:13:14.000Z",
"data": {
"value": "completed",
"trip_id": "123E4567-E89B-12D3-A456-426655440000",
"trip_metadata": { "customer": "1234" },
"distance": 12578, // distance in meters
"duration": 3600, // total duration of the trip in seconds
"duration_at_destination": 903 // total time spent at destination in seconds
},
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"type": "trip",
"version": "2.0.0"
}

Geofence markers

HyperTrack provides the capability to send you geofence visit markers from your HyperTrack SDK integration.

Webhook payload is following this data structure:

{
"created_at": "2019-07-01T14:01:00.000Z",
"recorded_at": "2019-07-01T14:00:09.000Z",
"data": {
"arrival": {
"location": {
"coordinates": [
-123.45677,
12.34567,
12.34
],
"type": "Point"
},
"recorded_at": "2019-07-01T14:00:00.000Z"
},
"duration": 9,
"exit": {
"location": {
"coordinates": [
-111.11111,
22.222222,
12.34
],
"type": "Point"
},
"recorded_at": "2019-07-01T14:00:09.000Z"
},
"geofence_id": "fed594a1-10c7-47e3-8aa3-f5fcaa265bdb",
"geofence_metadata": {"station": "B"}
"geometry": {
"coordinates": [
-101.625463,
32.347361
],
"type": "Point"
},
"marker_id": "123e4567-e89b-12d3-a456-426614174000",
"route_to": {
"distance": 1234,
"duration": 930,
"idle_time": 12
},
"trip_id": "01380bff-5b72-4ae6-a8c5-71e694b1c3c9",
"value": "exit"
},
"location": {
"type": "Point",
"coordinates": [-111.11111,22.222222,12.34]
},
"device_id": "321E4567-AAAA-12D3-A456-42661417400",
"account_id": "111e3322-e89b-12d3-a456-426614174000",
"type": "geofence",
"version": "2.0.0"
}

In the example, you can see that device_id with value 321E4567-AAAA-12D3-A456-42661417400 exited the geofence with geofence_id fed594a1-10c7-47e3-8aa3-f5fcaa265bdb.

For further reference, you may visit this guide to receive and process geofence visit events.

Location updates

Location time series data where each location in the stream includes coordinates and the optional fields speed, altitude, bearing, and accuracy when available.

{
"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": {
"geometry": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"speed": 0.0,
"bearing": 313.94
},
"version": "2.0.0"
}

Location events are sent with a high frequency (~ 100x more than activity events).

  • Data: Current location of the device in GeoJSON format. Altitude, the optional third parameter in the coordinates array, is the current device elevation in meters, relative to the sea level on iOS and relative to the WGS 84 reference ellipsoid on Android.
  • Location Accuracy (Optional): The estimated horizontal accuracy of the location, radial, in meters. When the location identifies the center of a confidence circle, the accuracy defines the radius of the circle (in meters). For Android, there is a 68% probability that the true location is inside the circle.
  • Bearing (Optional): The horizontal direction of travel, measured in degrees and relative to true North. Degrees start at true North and continue clockwise around the compass (north is 0, east is 90, south is 180, west is 270 degrees).
  • Speed (Optional): Speed of travel in meters per second.
Device location payload
"location": {
"speed": 4.20,
"accuracy": 14.09,
"bearing": 193.12,
"geometry": {
"type": "Point",
"coordinates": [
35.1016383,
47.8391314,
65.40
]
},
"recorded_at": "2019-07-18T18:01:59.064000Z",
}

Use the location object to display the location of a device on a map. It is important to understand the GeoJSON format to handle the data correctly:

  • Type can only be "Point" in this scenario
  • Coordinates is an array of 2-3 values (the last being optional) with the following format: [longitude, latitude, altitude]

The accuracy value is often used to draw a "halo effect" around the location dot with the accuracy (in meters) value being the radius of the surrounding ring. In addition, bearing (in degrees starting at due north) is used to draw a directional indicator at the location dot.

Location Map

Battery status changes

Battery status changes include values such as low, normal and charging

Battery status property
"battery": "normal"

Device objects contain a battery property to indicate the state of the device battery. The property can take one of the following values: low, normal, or charging

tip

If you would like to receive battery state updates as they come in, it is recommended to use battery updates webhooks. This enables reacting to low battery risks as they happen.

{
"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.6398983 124]
},
"version": "2.0.0"
}

HyperTrack sends battery updates to indicate the battery health. These events include details on charge, discharge and low battery.

info

Battery updates can be combined with outages as a leading indicator for tracking outages.

Identifying devices by name and metadata in webhook payloads

Optionally, webhook payload can also contain name and metadata associated with the device as shown in the example below with name and metadata keys.

{
"created_at": "2019-07-01T20:00:01.247377Z",
"device_id": "00112233-4455-6677-8899-AABBCCDDEEFF",
"recorded_at": "2019-07-01T20:00:00.000000Z",
"type": "device_status",
"data": {
"value": "active",
"activity": "walk"
},
"location": {
"type": "Point",
"coordinates": [-6.2755, 57.6398983, 124]
},
"version": "2.0.0",
"name": "Alex",
"metadata": {
"store_manager_id": 1
}
}
note

Device name and metadata addition to webhook payloads is in limited Beta with select customers. Please contact us to get access.

Nearby API request completion

In addition to GET /devices/nearby API, you will also get notified about the completion of a request via webhook notification with below payload example structure. To see how Nearby API works, please see this guide.

Notification payload for Nearby API completion will look like this:

{
"created_at": "2020-04-29T02:25:59.906839Z",
"type": "nearby_devices_request",
"data": {
"value": "completed",
"request_id": "09f63b10-9bbc-4b24-af1a-d8ac84644fcc",
"location": {
"coordinates": [
-122.402007, 37.792524
],
"type" : "Point"
},
"metadata": {
"team": "san_francisco",
"gig_type": "delivery"
}
"radius": 1000
},
'version': '2.0.0'
}

Webhooks setup

To get started with webhook integration, the HyperTrack dashboard allows you add your webhook URL on the Setup page.

Just enter your webhook URL and click on Add Webhook. Once entered, it will immediately change to Receiving markers and location update if Include location updates option is selected.

important

If you select to receive location updates from devices in your account, it will increase number of webhooks by 10-40x. Please use this option only if your business use case requires real-time location update stream from all locations from all tracked devices.

You may be able to opt-in later to receive location updates should your requirements change. Please note it takes up to 10 minutes for your configuration changes to take effect.

Setup Screen

Validate webhook notifications

Your webhook payload can be validated to confirm as being sent by HyperTrack.

All webhook payloads sent to your server contain x-hypertrack-signature header. This header is an HMAC-SHA1 signature generated using your webhook request payload and your account's secret key. Your secret key can be found in your account's dashboard setup page as SecretKey.

Please review code examples below for guidance on how to perform signature verification.

important

Please ensure to process raw body from the HTTP POST request to validate the contents of the webhook payload.

const crypto = require('crypto');
// Get webhook payload as received by your server end point. It needs to be the raw payload coming from the HTTP POST body that came to your server end point.
const webhook_payload = '[{"created_at": "2020-06-09T22:44:29.554924Z", "device_id": "ABCD182-6998-4686-AB2E-CF8F998A1EB6", "recorded_at": "2020-06-09T22:44:25.999000Z", "type": "location", "data": {"geometry": {"type": "Point", "coordinates": [-122.294112, 37.864945, 15.14]}, "speed": 1.003556110578331, "accuracy": 14.733237162224144, "bearing": 179.2877726443533}, "version": "2.0.0"}]'
// Get your SecretKey from the setup page in your account dashboard
const signatureKey = '{your_secret_key}'
const hmac = crypto.createHmac('sha1', signatureKey);
hmac.update(webhook_payload);
const signature = hmac.digest('hex');
// Verify signature from `x-hypertrack-signature` header
const webhook_payload_signature = '{signature_value}'
if (signature === webhook_payload_signature) {
console.log('Verification is successful');
} else {
console.log('Verification failed');
}

Troubleshooting webhook integration

Please review common issues below for suggestions on how to resolve them.

Webhooks payloads are not sent to your server

To confirm if your webhook server is working as expected, you may send a test event by clicking on three dots on the webhook setup screen and and then clicking on Send test event option.

Setup Screen

You will receive a webhook test payload that will be like this:

[
{
"recorded_at": "2019-02-27T22:50:24.538000Z",
"data": {
"altitude": 495.2,
"bearing": 90,
"location": {
"coordinates": [
-6.2755,
57.6398983
],
"type": "Point"
},
"location_accuracy": 14.087,
"speed": 0
},
"device_id": "TEST_DEVICE_ID",
"type": "location",
"account_id": "0"
}
]

If you have not received the request, then you may want to verify if your server is reachable by making a POST request with a tool of your choice to your webhook server URL. Otherwise, your server will be receiving webhooks from HyperTrack once devices under your account generate location data.

note

You will likely not receive webhooks right away. We offer the capability to send test events (upon click on the three dots on the screen above). This will allow you to test your implementation.


Multiple webhook payloads received for the same event

When you observe multiple webhook payloads received for the same event, for example, a trip completion event, you need to check if your URL end point returns a successful and timely response for each webhook HTTP POST request sent to your server.

Otherwise, HyperTrack will attempt to re-send the same request up to three times before giving up.

Questions?

If you would like to get help with location tracking needs for your app users' devices, questions or comments on any of the topics above, please do not hesitate to contact us.