Register a Callback Listener URL:

POST /callbacks/{account}

Registers a URL endpoint at which an account will receive callback messages from the Device Location service. There are two different types of callback messages, and you register to receive each one separately:

  • Location callbacks: sent when asynchronous device location reports are ready, and when monthly usage reaches a set trigger point
  • DeviceLocation callbacks: contain device location information from POST /devicelocation requests

The messages will be REST messages POSTed to the target URLs. You are responsible for creating and running a listening process on your server at those URLs to receive and parse the messages. You must run separate listening services at separate target URLs for each type of callback message that you register for.

Contents

See also:
About Callback Services
List Callback Listeners
Deregister a Callback Listener

Uses

Callback messages are secured with a shared secret key and SHA256 HMAC signatures. The response to this request (to register a callback listener) will contain the secret key in the header, and you must save the shared key to be able to authenticate and validate callback messages.

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/loc/v1/callbacks/{account}

Resource Path and Query Parameters

The account name must be included in the path.

Parameter Name Data Type Description
account
required		 string The name of the billing account for which you want to receive callback messages. An account name is usually numeric, and must include any leading zeros.

Header Parameters

The request header must contain a current ThingSpace authorization bearer token and a valid VZ-M2M session token, and must set the content-type to JSON.

Parameter Name Data Type Description
Authorization
required		 string HTTP Authorization bearer token.
VZ-M2M-Token
required		 string A valid session token returned by POST /api/m2m/v1/session/login.
Content-Type
required		 string Must be application/json.

Request Body

The body specifies the callback service that is being subscribed to and the URL where the listening service is running.

Parameter Name Data Type Description
name
required		 string The name of the callback service that you want to subscribe to:
url
required		 string The address on your server where you have enabled a listening service for the specific type of callback messages. Specify a URL that is reachable from the Verizon data centers. If your service is running on HTTPS, you should use a one-way authentication certificate with a white-listed IP address.

Example Request Body

{
  "name": "Location",
  "url": "http://10.120.102.183:50559/CallbackListener/LocationServiceMessages.asmx"
}

Success Responses

Status 200

Parameter Name Data Type Description
accountName string The name of the billing account for which callback messages will be sent.
serviceName string The name of the callback service, which identifies the type and format of messages that will be sent to the registered URL.

Note that the response contains the secret key in the header, for example:

Shared-Key: "020c9ad3-077c-4ab3-979a-2c6184599498"

Example Success Response

{
  "accountName": "0212312345-00001",
  "serviceName": "Location"
}

Failure Responses

Status 400

All error messages are returned in this format:

{
  "errorCode": "error code string",
  "errorMessage": "error message string"
}

Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.