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 /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.

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.

# 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 /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. ## 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}](/docs/standard-apis/connectivity-management/api-endpoints/connectivity-callbacks/register-callback/registercallback) ## 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](https://thingspace.verizon.com/documentation/api-documentation.html#/http/session-management/guides/getting-started). | Parameter Name | Data Type | Description | |:----------------|:-----------|:-------------| | **Authorization** *(required)* | string | HTTP Authorization bearer token: <br> `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: <br> `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: <br> `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 ```json { "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 ```json { "accountName": "0000123456-00001", "serviceName": "Location" } ``` ## Failure Responses All error messages are returned in this format: ```json { "errorCode": "The 3-digit HTML error code", "errorMessage": "string" } ``` Error codes and messages are listed on the [Error Codes page](https://thingspace.verizon.com/documentation/api-documentation.html#/http/device-location/error-codes), along with explanations and suggestions for corrective actions.

Verizon 5G Edge API Portal

Register Callback Listener