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.

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:

• Asynchronous API Responses - The status or requested information from API requests that take time to process, such as activating devices.
• ThingSpace Platform Notifications - Messages sent to notify your application about a change that was made outside of the API interface, such as a manual change made through ThingSpace Manage, the expiration of a promotional code for a device, or an upcoming date when a suspended device will automatically be returned to active status.
• Device Messages - SMS messages sent by devices through the ThingSpace Platform to your application.

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:

• Enable white-listing on your firewall or front-end server and add the Verizon M2M Data Center IP addresses to the white list. This will allow your servers to reject requests from other IP addresses. Your Verizon Sales Engineer can provide you with the IP addresses.
• Install a one-way certificate and enable HTTPS. You must use a certificate from a third-party certificate service; a self-signed certificate will not work. The Verizon M2M Data Center will check the certificate at the start of every session to verify that the registered IP address leads to your servers.

Callback Reliability and Retries

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

• Your callback listener web service must acknowledge receipt of a callback message by sending back a 2xx status code.
• For every callback message, ThingSpace waits for an acknowledgement for 15 seconds. If no acknowledgement is received, we determine that it is a failure.
• Callback messages that are not acknowledged by your application are resent by ThingSpace 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.

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

• For every callback message, ThingSpace waits for an acknowledgement for only 2 seconds, and if not acknowledged, we determine that it is a failure.
• ThingSpace retries the callback immediately (after 1 second) and if no acknowledgement on the second attempt, it is a failure and we do not try again, for a total of only two attempts.

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:

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:

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.