Callback Registration Service

The Callback Registration Service provides APIs that let you register and unregister URLs where you would like to receive callback messages from M2M 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 M2M Platform service.
UnregisterCallback Stops the M2M Platform from sending callback messages for the specified account and service.

Overview

The Verizon M2M 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 M2M 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 M2M 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 M2M 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 M2M Platform should include in each message. The M2M 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

Your callback listener web service must acknowledge receipt of a callback message by sending back the request ID within 15 seconds of receiving the message. Callback messages that are not acknowledged by your application will be resent by the M2M Platform three more times at 5 minute intervals, for a total of 4 attempts to send the message. Failed (unacknowledged) callback messages are archived for 30 days. During the 30 day period, you can contact support with the Request ID of failed callbacks and ask for them to be resent.

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 M2M 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.)
DeviceSuspensionStatus Callback messages containing information about the suspended status of devices, in response to GetDeviceSuspensionStatus requests.
SMSDeliveryConfirmation Indicates that an SMS Message sent through the SendSmsMessage API was received and acknowledged by the device.

Receiving M2M Platform Notification Callbacks

You can subscribe to these services to receive notifications about device changes that were not initiated through the M2M 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 M2M 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 M2M Platform also sends a callback message when a 4G device completes SIM Over-The-Air (OTA) activation.

PromoChange The M2M 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 M2M 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.