Register Callback Listener
POST /callbacks/{accountName}
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 /devicelocationrequests
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.
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.
HTTP Request
POST https://thingspace.verizon.com/api/loc/v1/callbacks/{accountName}
Resource Path and Query Parameters
| Parameter Name | Data Type | Description |
|---|---|---|
| accountName (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 token and a current VZ-M2M session token. For more details on how to get these tokens, visit Getting Started.
| Parameter Name | Data Type | Description |
|---|---|---|
| Authorization (required) | string | HTTP Authorization bearer token: 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: Content-Type: 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: Location for Device Location Report and usage alerts notifications or DeviceLocation for device location information responses. |
| 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-eeee-ffff-gggg-2c6184599498"
Example Success Response
{
"accountName": "0000123456-00001",
"serviceName": "Location"
}Failure Responses
All error messages are returned in this format:
{
"errorCode": "The 3-digit HTML error code",
"errorMessage": "string"
}Error codes and messages are listed on the Error Codes page, along with explanations and suggestions for corrective actions.