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.|
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:
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.
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:
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.
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:
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.|
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:
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:
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.|
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.
This callback service provides two types of messages: