Register a Callback Listener URL:

POST /callbacks/{accountname}

Registers a URL at which an account receives asynchronous responses and other messages from a ThingSpace Platform callback service. The messages are REST messages. You are responsible for creating and running a listening process on your server at that URL to receive and parse the messages.

Contents

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

Uses and Requirements

All Verizon callbacks originate from one of these IP addresses:

  • 3.87.163.45
  • 3.91.119.203
  • 54.197.62.209
  • 35.165.205.14
  • 54.200.43.232
  • 34.216.81.234
  • 137.117.33.109
  • 168.62.173.153
When you register a callback, we only allow the following ports: 
  • 80
  • 443
  • 9001-9006
  • 50551-50559
  • 28200-28220

Request Components

HTTP Request

POST https://thingspace.verizon.com/api/m2m/v1/callbacks/{accountname}

Resource Path and Query Parameters

The account name must be included in the path.

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.
Note: Use “TestAccount-2” when trying this request with the simulator.

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 /session/login.
Content-Type
required
string Must be application/json.

Request Body

The body specifies the callback service that you are subscribing 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. Set this to one of the following values:

AlertService
Callback messages sent when trigger conditions are met.
CarrierService
Asynchronous responses for all requests that change a device’s state and metadata, including: activate, suspend, restore, and deactivate. Note: the Assign and Unassign SIM-Secure APIs will respond on this callback service.
DevicePRLInformation
Asynchronous responses containing current device PRL values, in response to POST /devices/actions/prl/list requests.
DeviceProfileService
Asynchronous responses for all requests that change a device’s profile status, including download, enable, disable, and delete.
DeviceService
Asynchronous responses to POST /devices/availability/actions/list and POST /devices/actions/upload requests.
DeviceSuspensionStatus
Asynchronous responses containing information about suspended devices in response to POST /devices/suspension/status requests.
DeviceUsage
Asynchronous responses about device usage in response to POST /devices/usage/actions/list/aggregate requests.
DiagnosticsService
Asynchronous responses for all requests that allow registering, status check for SCEF devices for notifications when there is a change in device’s state (awake/sleep).
EnhancedConnectivityService
This callback service provides two types of messages:
  • The contents of SMS messages sent from your devices to 750075007500 or to 900060005010.
  • Notification of when messages sent through POST /sms requests are sent by the network to devices.
ExternalProvisioningChanges
Receive callback messages when provisioning changes are made outside of the ThingSpace APIs, such as when a user performs one of the following provisioning actions from an interactive Verizon system:
  • Activate
  • Deactivate
  • Suspend
  • Resume
  • Change ESN
  • Change MEID
  • Change MDN
IntelligenceService
Receive callback notifications from the Intelligence service such as real-time network conditions, static coverage, FWA coverage, site proximity and device experience score.
NiddService
Asynchronous responses (second callback) for all requests that change a device’s state and metadata, including: activate, suspend, restore, deactivate and changedeviceserviceplan, for Nidd Configuration success/failure, for NB-IoT devices only.
Asynchronous responses for all requests that allow sending NIDD data (MT) to the device; and asynchronous callbacks for the NIDD data messages (MO) coming from the device.
PromoChanges
Receive unsolicited callbacks for changes to promotional codes. A PromoChange callback message is sent shortly after the end of a device’s billing cycle if a promotional package was removed during the billing cycle.
ResumeTrackingNotification
Receive callback messages to notify you about suspended devices that are automatically returned to active status. ThingSpace sends a callback message 7 days before a suspended device will auto-resume.
SMSDeliveryConfirmation
Indicates that an SMS Message sent from a POST /sms request was received and acknowledged by the device.
StateService
Aynchronous responses from PUT /devices/actions/gotostate requests.

NOTE: You cannot register a callback service through the REST API if the same callback service has been registered through the SOAP API.

SubscriptionNotificationService
Notification that data will be partially or completely "Throttled".
url
required
string

The address on your server where you have enabled a listening service for 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. In most cases, you should register each service type to a unique a URL address.

When you register a callback, we only allow the following ports: 

  • 80
  • 443
  • 900-9006
  • 50551-50559
  • 28200-28220
username
optional
string The user name that the M2M Platform should return in the callback messages. If you are handling multiple accounts and you want them to use the same callback address, you can use this credential to identify the account that a particular message is associated with. Pass an empty element if you don’t want to include a username for this account and service type. Do not use your UWS/M2M username, or any other username that you want to remain private or secret.

NOTE: Must be 40 characters or fewer.

password
optional
string The password that the M2M Platform should return in the callback messages. Pass an empty element if you don’t want to include a password for this account and service type. Do not use your UWS/M2M password, or any other password that you want to remain private or secret.

NOTE: Must be 40 characters or fewer.

Example Request Body

{
  "name": "CarrierService",
  "url": "http://10.120.102.183:50559/CallbackListener/CarrierServiceMessages.asmx"
}

Success Responses

Status 200

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

Example Success Response

{
  "accountName": "122333444-00002",
  "serviceName": "CarrierService"
}

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 Messages page, along with explanations and suggestions for corrective actions.

Try It Out!