About Connectivity Management API Callback Services

Contents

Overview

The ThingSpace Connectivity Management API uses callback services (also called webhooks) to send messages to your application. There are three broad categories of callback messages:

  • Asynchronous API Responses - Messages that contain the status or requested information from API requests that take time to process, such as activating devices.
  • ThingSpace 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 a Verizon portal, 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 ThingSpace 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 REST messages that conform to the Callback JSON schema. You then need to register the URL of your web service through the Connectivity Management API so that it knows where to send the callback messages.

You can run multiple callback listening services on a single server, but your application will be more robust if you use a separate port for each type of callback message that you plan to receive.

You only need to register once for each type of callback message that you want to receive. You do not need to subscribe to all messages – only to those that are applicable to your needs.

NOTE: 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 ThingSpace servers. The IP addresses are:

  • 137.117.33.109
  • 168.62.173.153
  • 3.87.163.45
  • 3.91.119.203
  • 54.197.62.209
  • 35.165.205.14
  • 54.200.43.232
  • 34.216.81.234

NOTE: To test your callback listening 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 you want ThingSpace to include in each message. It will include the username and password as plain text in the callback messages. ThingSpace 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:

  "password": "string",
  "username": "string"

To increase security when receiving callback messages from ThingSpace, you can implement these protocols:

  • Enable white-listing on your firewall or front-end server and add the ThingSpace IP addresses to the white list. This will allow your servers to reject requests from other 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. ThingSpace will check the validity of the certificate at the start of every session.

Callback Reliability

Your callback listener web service must acknowledge receipt of a callback message by sending back a 2xx status code. Callback messages that are not acknowledged by your application will be 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.

Receiving Asynchronous API Callbacks

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

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

Below are the callback services that return asynchronous API responses:

Callback Service Description
CarrierService Asynchronous responses from all requests that change device states and metadata: activate, suspend, restore, deactivate, move, change cost center, change service plan, etc.
DevicePRLInformation Callback messages containing current device PRL values, in response to POST /devices/prl/actions/list requests.
DeviceProfileService Asynchronous responses for all requests that change a device’s profile status, including download, enable, disable, and delete.
DevicePromoUsage placeholder text
DeviceService Callback messages about devices from POST /devices/actions/upload requests.
DeviceSuspensionStatus Callback messages containing information about the suspended status of devices, in response to POST /devices/suspension/status requests.
DeviceUsage Callback messages about device usage from 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 Callback messages from POST /sms to let you know when your messages have been sent to devices. (This callback service is also used to receive SMS messages sent from devices to your application.)
PmecService placeholder
SMSDeliveryConfirmation Indicates that an SMS Message sent through POST /sms was received and acknowledged by the device.
StateService Asynchronous responses from PUT /devices/actions/gotostate requests.
VIPCallbackSerivce placeholder

Receiving ThingSpace Notification Callbacks

You can subscribe to these services to receive notifications about device changes that were not initiated through ThingSpace 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
AlertService Callback messages sent when trigger conditions are met.
ExternalProvisioningChanges Non-API-initiated provisioning transactions. For example, ThingSpace would send a message if a Verizon business portal user made any of the following changes:
  • Activate
  • Deactivate
  • Suspend
  • Restore
  • Change ESN
  • Change MEID
  • Change MDN
ResumeTrackingNotification Messages to notify you about suspended devices that will automatically return to active status. ThingSpace will send a callback message 7 days before a suspended device will auto-resume.
SubscriptionNotificationService Notifications to alert the user that data services will be "Throttled" either partially or completely as well as alerting when data usage has exceeded a set limit.

Receiving Device Message Callbacks

Sophisticated IoT applications often need to process information sent from devices so that appropriate actions can be taken. You can use the callback service 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 or to 900060005010.
  • Notification of when POST /sms messages are sent to devices.

Callback Best Practices

To see more information about best practices for callbacks, please visit Callback Best Practices.

Callback Examples

CarrierService

Activate

{
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[
    {
      "id":"352452060026934",
      "kind":"IMEI"
    }
  ],
  "deviceResponse":{
    "activateResponse":{
      "deviceIds":[
        {
          "id":"10-digit phone number",
          "kind":"mdn"
        },
        {
          "id":"15-digit IMSI",
          "kind":"imsi"
        },
        {
          "id":"20-digit ICCID",
          "kind":"iccId"
        },
        {
          "id":"1+ 10-digit phone number",
          "kind":"msisdn"
        },
        {
          "id":"10-digit MIN",
          "kind":"min"
        }
      ],
      "ipAddress":"10.224.48.88",
      "state":"Active",
      "servicePlan":"84638",
      "featureCodes":[

      ],
      "deviceCredential":{
        "username":"{10-digit MDN}@vzw3g.com",
        "password":"{password}"
      }
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Suspend

{
  "username":"",
  "password":"",
  "requestId":"5b645698-162f-4897-889d-c61275ab1afc",
  "deviceIds":[
    {
      "id":"14-character MEID",
      "kind":"MEID"
    },
    {
      "id":"10-digit phone number",
      "kind":"MDN"
    }
  ],
  "deviceResponse":{
    "suspendResponse":{
      "expectedResumeDate":"05/25/2018",
      "maxSuspendDaysAllowed":180,
      "numDaysSuspendedLast12Months":93,
      "numDaysSuspendAllowedCurrent12Months":87
    }
  },
  "comment":"Device Suspended - Applicable Charges Will Continue",
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Restore

{  
  "username":"",
  "password":"",
  "requestId":"52288eff-c306-44f0-9e73-0c3143ea9e7b",
  "deviceIds":[  
    {  
      "id":"15-digit IMEI",
      "kind":"imei"
    },
    {  
      "id":"20-digit ICCID",
      "kind":"iccid"
    }
  ],
  "deviceResponse":{  
    "restoreResponse":{  
       "restored":true
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Deactivate

{  
  "username":"",
  "password":"",
  "requestId":"eb3406b0-15fc-4473-8e84-b92cfb67f22d",
  "deviceIds":[  
    {  
      "id":"15-digit IMEI",
      "kind":"imei"
    },
    {  
      "id":"20-digit ICCID",
      "kind":"iccid"
    }
  ],
  "deviceResponse":{  
    "deactivateResponse":{  
      "deactivated":true
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Change Device Contact Info

{
  "username":"",
  "password":"",
  "requestId":"24da9f9a-d110-4a54-86b4-93fb76aab83c",
  "deviceIds":[
    {  
      "kind":"ESN",
      "id":"11-digit ESN"
    },
    {
      "kind":"ESN",
      "id":"11-digit ESN"
    }
  ],
  "deviceResponse":{
    "contactInfoResponse":{
      "accountName":"0000123456-00001"
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Change Device Cost Center

{
  "username": "",
  "password": "",
  "requestId": "3e4a42ca-6dfa-460e-9803-f677b069a694",
  "deviceIds": [
    {
      "id": "14-character MEID",
      "kind": "Meid"
    }
  ],
  "deviceResponse": {
    "deviceCostCenterResponse": {
      "costCenterCode": "VZW103",
      "primaryPlaceOfUse": {
        "address": {
          "addressLine1": "9808",
          "addressLine2": "Scranton Road",
          "city": "San Diego",
          "state": "CA",
          "country": "US",
          "zip": "92121",
          "zip4": "01234",
          "phone": "{10-digit phone number}",
          "phoneType": "M",
          "emailAddress": "zaffod@theinternet.com"
        },
        "customerName": {
          "firstName": "Zaffod",
          "lastName": "Beeblebrox",
          "middleName": "Q",
          "title": "President",
          "suffix": "I"
        }
      }
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Change Device Custom Fields

{  
  "username":"",
  "password":"",
  "requestId":"c8de7c1d-59b9-4cf3-b969-db76cb2ce509",
  "deviceIds":[  
    {  
      "id":"10-digit phone number",
      "kind":"mdn"
    }
  ],
  "deviceResponse":{  
  },
  "comment":"Success",
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Change Device Identifier

{  
  "username":"",
  "password":"",
  "requestId":"a28892ea-6503-4aa7-bfa2-4cd45d42f61b",
  "deviceIds":[  
    {  
      "id":"11-digit ESN",
      "kind":"ESN"
    }
  ],
  "deviceResponse":{  
    "changeIdentifierResponse":{  
      "deviceIds":[  
        {  
          "id":"14-character MEID",
          "kind":"Meid"
        }
      ],
      "servicePlan":"M2M_4G"
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Change Device Service Plan

{
  "username":"",
  "password":"",
  "requestId":"c8de7c1d-59b9-4cf3-b969-db76cb2ce509",
  "deviceIds":[
    {
      "id":"10-digit phone number",
      "kind":"mdn"
    }
  ],
  "deviceResponse":{
    "deviceChangeServicePlanResponse":{
      "servicePlan":"M2M5GB",
      "effectiveDate":"12/25/2017 12:00:00 AM"
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Move Device

{
  "username":"",
  "password":"",
  "requestId":"ec682a8b-e288-4806-934d-24e7a59ed889",
  "deviceIds":[
    {
      "id":"11-digit ESN",
      "kind":"Esn"
    }
  ],
  "deviceResponse":{
    "usageResponse":[ ],
    "moveDeviceResponse":{
      "deviceIds":[
        {
          "id":"11-digit ESN",
          "kind":"Esn"
        }
      ],
      "accountName":"0000123456-00001"
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

DeviceService

Check Device Availability

{
  "username":"",
  "password":"",
  "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
  "deviceResponse":{
    "checkDeviceAvailabilityResponse":{
      "deviceInfo":[
        {
          "device":[
            {
              "id":"15-digit IMEI",
              "kind":"IMEI",
              "deviceSku":"VZW090000450004",
              "productType":"Modem",
              "deviceFound":true
            },
            {
              "id":"20-digit ICCID",
              "kind":"ICCID",
              "deviceFound":true
            }
          ],
          "associatedWithMTN":true,
          "deviceSimPair":true
        },
      ],
      "accountName":"0000123456-00001"
    }
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

DevicePRLInformation

{
  "username":"",
  "password":"",
  "requestId":"5b645698-162f-4897-889d-c61275ab1afc",
  "deviceIds":[
    {
      "id":"14-character MEID",
      "kind":"MEID"
    },
    {
      "id":"10-digit phone number",
      "kind":"MDN"
    }
  ],
  "deviceResponse":{
    "prlInformationResponse": {
      "prlVersion": "523310"
    },
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

DeviceSuspensionStatus

{
  "username": "",
  "password": "",
  "requestId": "904dcdc6-a590-45e4-ac76-403306f6d883",
  "deviceResponse": {
    "deviceSuspensionStatusResponse": [
      {
        "deviceIds": [
          {
            "id": "15-digit IMEI",
            "kind": "imei"
          }
        ],
        "state": "suspend",
        "suspendDate": "2017-12-21 00:00:00",
        "expectedResumeDate": "2018-03-20",
        "daysRemainingAutoResume": "90",
        "maxSuspendDaysAllowed": "180",
        "numDaysSuspendedLast12Months": "0",
        "numDaysSuspendAllowedCurrent12Months": "91",
        "timesSuspendedLast12Months": "1"
      },
      {
        "deviceIds": [
          {
            "id": "20-digit ICCID",
            "kind": "iccid"
          }
        ],
        "state": "suspend",
        "suspendDate": "2017-12-21 00:00:00",
        "expectedResumeDate": "2018-03-20",
        "daysRemainingAutoResume": "90",
        "maxSuspendDaysAllowed": "180",
        "numDaysSuspendedLast12Months": "0",
        "numDaysSuspendAllowedCurrent12Months": "91",
        "timesSuspendedLast12Months": "1"
      }
    ]
  },
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

DeviceUsage

{
  "username":"",
  "password":"",
  "requestId":"24da9f9a-d110-4a54-86b4-93fb76aab83c",
  "deviceResponse":{
    "prlInformationResponse":{},
    "smsDeliveryResponse":{},
    "usageResponse":[
      {},
      {
        "deviceIds":[
          {
            "id":"10-digit phone number",
            "kind":"Mdn"
          },
          {
            "id":"14-character MEID",
            "kind":"Meid"
          }
        ],
        "dataUsage":"0",
        "smsUsage":"0",
        "startDate":"2014-02-02T00:00:00.0000000",
        "endDate":"2014-02-25T00:00:00.0000000"
      }
    ]
  },
  "comment":"Request Completed Processing",
  "summary":{
    "devicesRequested":0
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

UploadDevices

{
   "username":"",
   "password":"",
   "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
   "deviceResponse":{
      "deviceUploadResponse":{
         "devices":[
            {
               "deviceIds":[
                  {
                     "id":"20-digit ICCID",
                     "kind":"Iccid"
                  },
                  {
                     "id":"15-digit IMEI",
                     "kind":"Imei"
                  }
               ],
               "lineStatus":"Device upload successful."
            },
            {
               "deviceIds":[
                  {
                     "id":"20-digit ICCID",
                     "kind":"Iccid"
                  },
                  {
                     "id":"15-digit IMEI",
                     "kind":"Imei"
                  }
               ],
               "lineStatus":"Device upload successful"
            },
            {
               "deviceIds":[
                  {
                     "id":"20-digit ICCID",
                     "kind":"Iccid"
                  },
                  {
                     "id":"15-digit IMEI",
                     "kind":"Imei"
                  }
               ],
               "lineStatus":"SIM Id is invalid"
            }
         ],
         "accountName":"0000123456-00001",
         "deviceSku":"VZW123456",
         "totalLineCount":"3",
         "failedLineCount":"1",
         "successLineCount":"2"
      }
   },
   "status":"Success",
   "callbackCount":1,
   "maxCallbackThreshold":4
}

EnhancedConnectivityService

SendSMSMessage

Per-Device Message

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"20-digit ICCID",
      "kind":"Iccid"
    },
    {  
      "id":"10-digit phone number",
      "kind":"Mdn"
    },
    {  
      "id":"15-digit IMEI",
      "kind":"Imei"
    },
    {  
      "id":"1+ 10-digit phone number",
      "kind":"Msisdn"
    }
  ],
  "comment":"SendSmsMessage,Performed action on device.",
  "status":"Success",
  "callbackCount":1,
  "maxCallbackThreshold":4
}

Request Complete Message

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "comment":"SendSmsMessage,Request Completed Processing."
  "summary": {
    "devicesRequested": 2
  },
  "callbackCount": 1,
  "maxCallbackThreshold": 4
}

SmsDeliveryConfirmation Callback Messages

Success after device acknowledgement

{  
  "username":"",
  "password":"",
  "requestId":"2c90bd28-ece4-42ef-9f02-7e3bd4fbff33",
  "deviceIds":[  
    {  
      "id":"10-digit phone numer",
      "kind":"Mdn"
    }
  ],
  "deviceResponse":{  
    "smsDeliveryResponse":{  
      "confirmation":"Delivered"
    }
  }
}

SMS Message from Device

{
  {
    "messages": [
      {
        "deviceIds": [
          {
            "id": "11-digit ESN",
            "kind": "esn"
          }
        ],
        "message": "testmessage1",
        "timestamp": "2016-01-01T12:29:49-08:00"
      },
      {
        "deviceIds": [
          {
            "id": "11-digit ESN",
            "kind": "esn"
          }
        ],
        "message": "testmessage2",
        "timestamp": "2016-01-01T12:31:02-08:00"
      }
    ]
  },
  "hasMoreData": false
}

ExternalProvisioningChanges

This is an example of an ExternalProvisioningChanges callback message sent when a system other than the Wireless Network Services API or ThingSpace Connectivity Management API activates a line of service for a device.

{
  "username":"",
  "password":"",
  "requestId":"24da9f9a-d110-4a54-86b4-93fb76aab83c",
  "deviceIds":[
    {
      "id":"15-digit IMEI",
      "kind":"Imei"
    }
  ],
  "deviceResponse":{
    "externalProvisioningChangeResponse":{
      "change":"Activate",
      "deviceInfo":{
        "accountName":"0000123456-00001",
        "billingCycleEndDate":"2017-11-30T00:00:00.0000000Z",
        "carrierInformations":[
          {
            "carrierName":"Verizon Wireless",
            "servicePlan":"M2M5GB",
            "state":"active"
          }
        ],
        "connected":true,
        "createdAt":"2017-11-27T14:03:21.0000000Z",
        "deviceIds":[
          {
            "id":"10-digit phone number",
            "kind":"mdn"
          },
          {
            "id":"15-digit IMSI",
            "kind":"imsi"
          },
          {
            "id":"15-digit IMEI",
            "kind":"imei"
          },
          {
            "id":"20-digit ICCID",
            "kind":"iccId"
          },
          {
            "id":"1+ 10-digit phone number",
            "kind":"msisdn"
          },
          {
            "id":"10-digit MIN",
            "kind":"min"
          }
        ],
        "groupNames":[
          "Default: West coast trucks"
        ],
        "ipAddress":"1.1.29.169",
        "lastActivationBy":"User Verizon",
        "lastActivationDate":"2017-11-27T14:13:37.0000000Z"
      }
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

GoToState

{
 "username":"",
  "password":"",
  "requestId":"595f5c44-c31c-4552-8670-020a1545a84d",
  "deviceIds":[
    {
      "id":"20-digit ICCID",
      "kind":"Iccid"
    },
    {
      "id":"15-digit IMEI",
      "kind":"Imei"
    }
  ],
  "deviceResponse":{
    "usageResponse":[],
    "goToStateResponse":{
      "deviceIds":[
        {
          "id":"20-digit ICCID",
          "kind":"Iccid"
        },
        {
          "id":"15-digit IMEI",
          "kind":"Imei"
        }
      ],
      "serviceName":"WAM",
      "stateName":"WAM Activate"
    }
  },
  "status" : "Success",
  "callbackCount" : 1,
  "maxCallbackThreshold" : 4
}

PromoChanges

ThingSpace sends messages when there are changes to the promotional codes for a line of service, such as when a promotional code expires. ThingSpace sends a PromoChange callback message shortly after the end of a device’s billing cycle if a promotional package was removed during the billing cycle.

NOTE: You can use the POST /devices/actions/list to see all active promotional codes for a device and the scheduled end date for each one.

{
  "username":"",
  "password":"",
  "requestId":"90682b54-66ad-4c1f-a0f2-f3bb77ea298b",
  "deviceIds":[
    {
      "id":"15-digit IMEI",
      "kind":"IMEI"
    }
  ],
  "deviceResponse":{
    "promoChangeResponse":{
      "change":"PromoCode Dropped.",
      "changeDate":"12/15/2017 12:00:00 AM"
    }
  }
}

ResumeTrackingNotification

{
  "username":"",
  "password":"",
  "requestId":"24da9f9a-d110-4a54-86b4-93fb76aab83c",
  "deviceResponse":{
    "deviceIds":[
      {
        "id":"10-digit phone number",
        "kind":"Mdn"
      },
      {
        "id":"14-character MEID",
        "kind":"Meid"
      }
    ],
    "comment":"Device will be auto resumed on - 12/15/2018 12:00:00 AM"
  }
}

SubscriptionNotificationService

Throttling Notification

{
   "requestId":"535a2d96-33d9-4b36-8246-31058ffd0ff1",
   "deviceIds":[
      {
         "id":"10-digit phone number",
         "kind":"Mdn"
      },
      {
         "id":"15-digit IMEI",
         "kind":"Imei"
      },
      {
         "id":"20-digit ICCID",
         "kind":"Iccid"
      },
      {
         "id":"32-digit EID",
         "kind":"Eid"
      },
      {
         "id":"1+ 10-digit phone number",
         "kind":"Msisdn"
      }
   ],
   "deviceResponse":{
      "subscriptionNotification":[
         {
            "accountName":"0000123456-00001",
            "timeStamp":"2019-10-28 05:41:39",
            "throttlingPercentage":"100%",
            "usage":"12348646456.000000",
            "usageUnits":"BYT"
            "stateName":"subscription name"
         }
      ]
   },
   "callbackCount":1,
   "maxCallbackThreshold":4
}

Data usage alert Notification

{
   "requestId":"535a2d96-33d9-4b36-8246-31058ffd0ff1",
   "deviceIds":[
      {
         "id":"10-digit phone number",
         "kind":"Mdn"
      },
      {
         "id":"15-digit IMEI",
         "kind":"Imei"
      },
      {
         "id":"20-digit ICCID",
         "kind":"Iccid"
      },
      {
         "id":"32-digit EID",
         "kind":"Eid"
      },
      {
         "id":"1+ 10-digit phone number",
         "kind":"Msisdn"
      }
   ],
   "deviceResponse":{
      "dataUsageAlertInformation":[
         {
            "accountName":"0000123456-00001",
            "timeStamp":"2019-10-28 05:41:39",
            "dataUsageAlertPercentage":"100%",
            "dataUsed":"12348646456.000000",
            "dataRemaining":"12348646456.000000",
            "dataUnits":"BYT"
            "stateName":"subscription name"
         }
      ]
   },
   "callbackCount":1,
   "maxCallbackThreshold":4
}