Callback Registration Service

The Callback Registration Service provides API methods that let you register and unregister URLs where you would like to receive callback messages from ThingSpace Platform services.

Web Service API Description
GetCallbackRegistrations Returns the name and URL of all callback services associated with a given account.
RegisterCallback Registers a URL where an account will receive callback messages from an ThingSpace Platform service.
UnregisterCallback Stops the ThingSpace Platform from sending callback messages for the specified account and service.

Overview

The ThingSpace Platform uses callback services (also known as "webhooks") to send messages to your application. There are several different callback services that fall into three broad categories of callback messages:

Subscribing to Callback Services

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

You only need to register once for each type of callback messages that you want to receive. You do not need to subscribe to all services -- only to those that are applicable to your needs. The easiest way to register is to use the UWS Explorer tool (included in the Tools and Examples folder in the SDK) or through a SOAP client using the steps described here. You can choose to write code that uses the RegisterCallback API method, but it's much faster to use UWS Explorer for the one-time registration and then go on to other things.

You will have to provide a way through your firewalls for the callback messages, such as by whitelisting the IP addresses used by the Verizon M2M servers. You (or someone at your company) should have received the list of IP addresses when your company was approved for API access to the ThingSpace Platform.

Your application will be more robust if you use a separate port for each callback service.

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

Callback Security

When you register to receive any type of callback messages, you can specify a username and/or password that the ThingSpace Platform should include in each message. The ThingSpace Platform will not interact with any sort of authentication system. It will include the username and password as plain text in the callback message, like this:

<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/">
  <s:Body xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xmlns:xsd="http://www.w3.org/2001/XMLSchema">
    <CallbackRequest xmlns="http://nphase.com/unifiedwebservice/v2">
      <Username>username_value</Username>
      <Password>password_value</Password>
      <RequestId>c8de7c1d-59b9-4cf3-b969-db76cb2ce509</RequestId>
      <Device>
        <Kind>mdn</Kind>
        <Identifier>8586928930</Identifier>
      </Device>
      <Data>
        <Data>
          .
          .
          .
        </Data>
      </Data>
    </CallbackRequest>
  </s:Body>
</s:Envelope>

To increase security when receiving callback messages from the Verizon M2M Data Center, you can implement these protocols:

Callback Reliability and Retries

The following rules are applied for callback services, except for callbacks for NIDD and Diagnositcs services:

The following rules are applied for callback messages for NIDD and Diagnostics services:

Receiving Asynchronous API Response Callbacks

For API service requests that require significant processing time, such as provisioning service for a device or changing a service plan, the ThingSpace Platform replies first with a synchronous response that simply acknowledges the request and allows your application to continue processing. Later, the platform sends an asynchronous callback message, reporting the results of the request.

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

Below are the callback services that return asynchronous API responses:

Callback Service Description
CarrierService

Asynchronous responses from all Carrier Service APIs:

DevicePRLInformation Callback messages containing current device PRL values, in response to GetDevicePRLInformation requests.
DeviceUsage Callback messages about device usage from Device Service APIs GetAggregateDeviceUsage and GetRatedDeviceUsage.
EnhancedConnectivityService Callback messages from the Enhanced Connectivity Service API SendSmsMessage. (This callback service is also used to receive SMS messages sent from devices to your application.)
SMSDeliveryConfirmation Indicates that an SMS Message sent through the SendSmsMessage API was received and acknowledged by the device.

Receiving ThingSpace Platform Notification Callbacks

You can subscribe to these services to receive notifications about device changes that were not initiated through the ThingSpace Platform APIs. You can use these messages to keep any information that your application stores in sync with the actual status.

The table below lists the callback services that provide notifications about external changes:

Callback Service Description
ExternalProvisioningChange

Non-API-initiated provisioning transactions. For example, the ThingSpace Platform would send a message if a Verizon online business portal user made any of the following changes:

  • Activate
  • Deactivate
  • Suspend
  • Restore
  • Change ESN
  • Change MEID
  • Change MDN

The ThingSpace Platform also sends a callback message when a 4G device completes SIM Over-The-Air (OTA) activation.

PromoChange The ThingSpace Platform sends messages when there are changes to the promotional codes for a line of service, such as when a promotional code expires. A PromoChange callback message will be sent shortly after the end of a device's billing cycle if a promotional package was removed during the billing cycle.
ResumeTrackingNotification Messages to notify you about suspended devices that will automatically return to active status. The ThingSpace Platform will send a callback message 7 days before a suspended device will auto-resume.

Receiving Device Message Callbacks

Sophisticated M2M applications often include processing information from devices so that appropriate actions can be taken. You can use the callback services listed below to receive messages that are originated by devices.

Callback Service Description
EnhancedConnectivityService

This callback service provides two types of messages:

  • The contents of SMS messages sent by your devices to 750075007500.
  • Notification of when SendSmsMessage requests are sent to devices.