Webhooks

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

Webhook types

Each webhook type has its own page with a sample payload and a description of the fields.

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.

Planning

Lifecycle

ETA & Delays

Timesheets & Billing

Webhook types

Order Webhooks

Route Webhooks

Worker Webhooks

Device Webhooks

Geotag, Geofence, and Trip Webhooks

Deprecated