About the Device Location API Callback Service

Contents

Overview

The ThingSpace Device Location API can send these callback messages to your application:

• Location: A notification when an asynchronous device location report is ready to be retrieved, or a different notification when monthly usage reaches a set trigger point
• DeviceLocation: The locations of devices from POST /devicelocation requests

Callback messages are REST messages that are POSTed to the URL endpoint specified in a POST /callbacks request. You are responsible for creating and running a listening process on your server at that endpoint to receive and parse the messages.

Receiving Asynchronous API Callbacks

For API requests that require significant processing time, such as getting the current location of thousands of devices, the Device Location API replies first with a synchronous response that simply acknowledges the request and allows your application to continue processing. Later, the platform sends one or more asynchronous callback messages, reporting the results of the request.

The synchronous response contains a unique Transaction ID. The callback messages will contain the same Transaction ID so that you can associate the callback with the original API request.

**NOTE: ** No callback is sent for a POST /locationreports request for cached location information (cacheMode=0) because the report is available immediately.

Subscribing to Callback Services

To receive callback messages, you will need to create and deploy a web service that can validate and process REST messages that conform to the callback JSON schema. You then need to register the URL of your web service so that ThingSpace knows where to send the callback messages.

NOTE: You will have to provide a way through your firewalls for the callback messages, such as by whitelisting the IP address used by the Verizon ThingSpace servers. That address is 68.128.212.217.

NOTE: To test your callback listening services in a non-production environment, you must have an external URL for the computer or server that is hosting the web services. ThingSpace cannot send callback messages to a system that does not have a URL.

Callback Security

Callback messages sent by the Device Location API use a shared secret key and HMAC signatures (SHA256) to let you verify the authenticity and integrity of the messages.

1. When you register to receive callback messages, the response will contain a “Shared-Key” in the header, like this:
   Shared-Key: "020c9ad3-077c-4ab3-979a-2c6184599498"
2. You must save the shared key to use when validating messages.
3. Callback messages sent by ThingSpace will have a SHA256 MAC signature in the header:
   "Mac": "43bb65d2987acfbc992ef435b9155aef1608d619e56b5b024a066437eebda462"
4. You can use the shared key to authenticate and validate the message payload. Note that you must ensure that the payload is formatted without any extra spaces and with keys sorted in alphabetical order to get the same MAC from the SHA256 algorithm. For example:
   {"aname":"0252078987-00001","expiryDate":"2018-04-01","status":"COMPLETED","txId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33"}

To increase security when receiving callback messages from ThingSpace, you can implement these protocols:

• Enable white-listing on your firewall or front-end server and add the ThingSpace IP address (68.128.212.217) to the white list. This will allow your servers to reject requests from other IP addresses.
• Install a one-way certificate and enable HTTPS. You must use a certificate from a third-party certificate service; a self-signed certificate will not work. ThingSpace will check the validity of the certificate at the start of every session.

Device Location Report Callback JSON Schema

Notification that a Device Location report is ready conform to this structure:

{
  "aname": "string",
  "txId": "string",
  "status": "string",
  "expiryDate": "date-time string"
}

Example Device Location Report Callback

{
  "aname": "0252078987-00001",
  "txId": "2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "status": "COMPLETED",
  "expiryDate": "2018-04-01"
}

Device Location Report Callback Parameter Definitions

Usage Alert Callback JSON Schema

Usage alerts conform to this structure:

{
  "accountNumber": "string",
  "currentDate": "string",
  "maxAllowance": "string",
  "rawUsage": "date-time string",
  "service": "string",
  "thresholdPercValue": "string"
}

Example Usage Alert Callback

{
  "accountNumber":"0252078987-00001",
  "currentDate":"2018-08-24T17:46:24 UTC",
  "maxAllowance":"5000",
  "rawUsage":"4501",
  "service":"Location",
  "thresholdPercValue":"90"
}

Usage Alert Calback Parameter Definitions