About Software Management Services API Callback Notifications

Overview

The ThingSpace Software Management Services API can use a callback service (webhook) to send messages to your application when new firmware/software versions are available and when upgrades start and finish.

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 so that ThingSpace knows where to send the callback messages.

NOTE: To receive callback messages from Verizon ThingSpace servers, you may need to create firewall rules white-listing the appropriate IP addresses provided by Verizon. The following IP addresses should be white-listed:

3.87.163.45
3.91.119.203
54.197.62.209
54.200.43.232
34.216.81.234
137.117.33.109
168.62.173.153
68.128.212.217

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

Callback Security

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 address to the white list. This allows 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 checks the validity of the certificate at the start of every session.

Callback JSON Schema

All callback messages conform to one of two structures. Note that elements will be empty if not applicable to the current callback type (for example, the firmwareList element will be an empty array in an upgradeProgress callback message).

It is important that you know which protocol that devices are using because that will determine if you are using the /v1 or /v2 resource path and the associated callback JSON Schema.

JSON Schema Reference for OMA-DM and LWM2M Devices using the /v1 Resource Path

{
  "accountName": "string",
  "participantName": "string",
  "type": "string",
  "username": "string",
  "password": "string",
  "firmwareList": [
    {
      "firmwareName": "string",
      "participantName": "string",
      "launchDate": "string",
      "releaseNote": "string",
      "model": "string",
      "make": "string",
      "fromVersion": "string",
      "toVersion": "string"
    }
  ],
  "upgradeScheduled": {
    "firmwareName": "string",
    "upgradeId": "string",
    "startDate": "string",
    "status": "string"
},
  "upgradeProgress": {
    "firmwareName": "string",
    "upgradeId": "string",
    "resultCode": "string",
    "resultReason": "string",
    "finishTime": "string"
},
  "upgradeFinished": {
    "firmwareName": "string",
    "upgradeId": "string",
    "deviceList": [
      {
      "imei": "string",
      "status": "string"
      }
    ]
  }
}

Calback Parameter Definitions

Property Name	Data Type	Description
accountName	string	The account name in the format ##########-#####
devicelist	array	The IMEIs and statuses of the devices that were included in the upgrade. Status is either “succeed” or “fail”
finishTime	string	The intended firmware upgrade finish time
firmwareList	array	List of newly available firmware if type=newFirmware, otherwise an empty array
firmwareName	string	The name of the firmware image that will be used for the upgrade.
fromVersion	string	The firmware version that must currently be on the device to upgrade.
launchDate	string	The release date of the firmware image.
make	string	The device make that the firmware applies to.
model	string	The device model that the firmware applies to.
password	string	The password provided when the callback URL was registered
releaseNote	string	Short description of the release
resultCode		“Succeeded” if the firmware upgrade request was successfully initiated.
resultReason		Additional notes about the resultCode.
startDate	string	Intended start date for a scheduled upgrade.
status	string	The status of a scheduled upgrade.
toVersion	string	The firmware version that will be on the device after an upgrade.
type	string	Callback type: newFirmware, upgradeScheduled, upgradeProgress, or upgradeFinished
upgradeFinished	object	Contains the final report of a completed upgrade, include the list of devices that were included.
upgradeId	UUID string	The UUID of the scheduled upgrade, returned by POST /upgrades when the upgrade was scheduled.
upgradeProgress	object	Contains information about an upgrade that has started if type=upgradeProgress, otherwise empty.
username	string	The username provided when the callback URL was registered

Example Callback

New Firmware callback

{
  "accountName":"1223334444-12345",
  "type":"newFirmware",
  "username":"",
  "password":"",
  "firmwareList": [
    {
      "firmwareName":"FOTA_Verizon_Model-A_01To02_HF",
      "launchDate":"2017-11-08 20:15:42.738 +0000 UTC",
      "releaseNote":"",
      "model":"Model-A",
      "make": "Verizon",
      "fromVersion":"VerizonFirmwareVersion-01",
      "toVersion":"VerizonFirmwareVersion-02"
    },
    { 
      "firmwareName":"FOTA_Verizon_Model-B_03To04_HF",
      "launchDate":"2017-10-11 05:25:12.738 +0000 UTC",
      "releaseNote":"",
      "model":"Model-B",
      "make": "Verizon",
      "fromVersion":"VerizonFirmwareVersion-03",
      "toVersion":"VerizonFirmwareVersion-04"
    } 
  ],
  "upgradeScheduled": {},
  "upgradeProgress": {},
  "upgradeFinished": {}
}

Upgrade Scheduled callback

{
  "accountName":"1223334444-12345",
  "type":"upgradeScheduled",
  "firmwareList": [],
  "upgradeScheduled": {
    "upgradeId":"f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "firmwareName":"FOTA_Verizon_Model-A_01To02_HF",
    "startDate":"2018-07-04 00:00:00 +0000 UTC",
    "status":"Scheduled"
  },
  "upgradeProgress": {},
  "upgradeFinished": {}
}

Upgrade Started callback

{
  "accountName":"1223334444-12345",
  "type":"upgradeProgress",
  "firmwareList": [],
  "upgradeScheduled": {},
  "upgradeProgress": {
    "firmwareName":"FOTA_Verizon_Model-A_01To02_HF",
    "upgradeId":"f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "resultCode":"Succeeded",
    "resultReason":"Successfully requested to upgrade server system.",
    "startTime":"2018-04-02 00:49:19 +0000 UTC"
  },
  "upgradeFinished": {}
}

Upgrade Finished callback

{
  "accountName":"1223334444-12345",
  "type":"upgradeFinished",
  "username":"",
  "password":"",
  "firmwareList": [],
  "upgradeScheduled": {},
  "upgradeProgress": {},
  "upgradeFinished": {
    "firmwareName":"FOTA_Verizon_Model-A_01To02_HF",
    "upgradeId":"f9ce4356-0812-4ae3-86ff-e34e46d11fae"
  }
}

JSON Schema Reference for HTTP Devices using the /v2 Resource Path


{
  "accountName": "string",
  "participantName": "string",
  "type": "string",
  "softwareList": [
    {
      "softwareName": "string",
      "model": "string",
      "make": "string",
      "distributionType": "string",
      "softwareFrom": "string",
      "softwareTo": "string",
      "launchDate": "string",
      "releaseNote": "string",
      "devicePlatformId": "string"
    }
  ],
  "campaignRequestQueued": {
    "softwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "schedStatus": "string"
  },
  "campaignRequestFailed": {
    "softwareName": "string",
    "campaignId": "string",
    "resultCode": "string",
    "resultReason": "string",
    "requestFailedDate": "string"
  },
  "campaignScheduled": {
    "softwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "schedStatus": "string",
    "resultCode": "string",
    "resultReason": "string"
  },
  "campaignAborted": {
    "softwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "resultCode": "string",
    "resultReason": "string",
    "abortedTime": "string"
  },
  "campaignCanceled": {
    "softwareName": "string",
    "campaignId": "string",
    "resultCode": "string",
    "resultReason": "string",
     "canceledTime": "string"
  },
  "campaignEnded": {
    "softwareName": "string",
    "campaignId": "string
  }
}

V2 Callback Parameter Definitions

Property Name	Data Type	Description
accountName	string	The account name in the format #########-#####

type	string	Callback type: newFirmware, upgradeScheduled, upgradeProgress, or upgradeFinished.
softwareList	array	List of software on the device.
softwareName		The name of the software.
model	string	The device model that the software applies to.
make	string	The device make that the software applies to.
distributionType	string	Valid values include: LWM2M, OMA, HTTP
softwareFrom	string	The name of the old software on the devicee.
softwareTo	string	The name of the software you are upgrading to.
launchDate	string	The software launch date.
releaseNote	string	Software release note.
devicePlatformId	string	The platform (Android, iOS, for example) that the software can be applied to.
CampaignRequestQueued	array
softwareName	string	The name of the software.
campaignId	string	Software upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
startDate		Campaign start date.
schedStatus	string	Status of the campaign. "CampaignRequestQueued."
campaignRequestFailed	array
softwareName	string	The name of the software.
campaignId	string	Software upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
resultCode	string	Campaign Request Failed
resultReason	string	Additional notes about the resultCode
requestFailedDate	string($date-time)	The date and time the request failed.
campaignScheduled	array
softwareName	string	The name of the software.
campaignId	string	Software upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
startDate	string	Campaign start date.
schedStatus	string	CampaignScheduled
resultCode	string	Schedule Success
resultReason	string	Additional notes about the resultCode
campaignAborted	array
softwareName	string	The name of the software.
campaignId	string	Software upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
startDate		Campaign start date.
resultCode	string	Schedule aborted.
resultReason	string	Additional notes about the resultCode
abortedTime	string($date-time)	The date and time the campaign was aborted.
campaignCanceled	array
softwareName	string	The name of the software.
campaignId	string	Software upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
resultCode	string	Schedule Cancelled
resultReason	string	Additional notes about the resultCode
canceledTime	string($date-time)	The date and time the campaign was canceled.
campaignEnded	string	The date the campaign ended.
softwareName	string	The name of the software.
campaignId	string	Software upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled

Example Callback

New software Callback

{
  "accountName":"1223334444-12345",
  "type":"newSoftware",
  "softwareList": [
    {
      "SoftwareName":"FOTA_Verizon_Model-A_01To02_HF",
      "model":"Model-A",
      "make": "Verizon",
      "distributionType": "HTTP",
      "softwareFrom":"VerizonFirmwareVersion-01",
      "softwareTo":"VerizonFirmwareVersion-02"
      "launchDate":"2017-11-08 20:15:42.738 +0000 UTC",
      "releaseNote":"",
      "devicePlatformId": "IoT"
    }
  ]
}

Campaign Queued Callback

{
  "accountName":"1223334444-12345",
  "type":"campaignReqeustQueued",
   "campaignRequestQueued": {
    "softwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "startDate": "2020-06-30",
    "schedStatus": "CampaignRequestQueued"
  }
}

Campaign Request Failed Callback

{
  "accountName": "1223334444-12345",
  "type": "campaignRequestFailed",
  "campaignRequestFailed": {
    "softwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "resultCode": "Campaign Request Failed",
    "resultReason": "Campaign request failed due to invalid condition of all devices",
    "requestFailedDate": "2020-06-26 21:09:28.274885082 +0000 UTC m=+349002.299663955"
  }
}

Campaign Scheduled Callback

{
  "accountName": "1223334444-123455",
  "type": "campaignScheduled",
  "campaignScheduled": {
    "softwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "startDate": "2020-06-29 00:00:00 +0000 UTC",
    "schedStatus": "CampaignScheduled",
    "resultCode": "Schedule Success",
    "resultReason": "Successfully scheduled campaign"
  }
}

Campaign Aborted Callback

{
  "accountName": "1223334444-123455",
  "type": "campaignAborted",
  "campaignAborted": {
    "softwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "resultCode": "Schedule Aborted",
    "resultReason": "Schedule aborted due to user request",
    "abortedTime": "2020-06-29 14:32:14.097811123 +0000 UTC m=+584371.553547629"
  }
}

Campaign Canceled Callback

{
  "accountName": "1223334444-123455",
  "type": "campaignCancelled",
  "campaignCanceled": {
    "softwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae",
    "resultCode": "Schedule Cancelled",
    "resultReason": "Schedule cancelled due to empty device list",
    "canceledTime": "2020-06-29 14:36:38.620273439 +0000 UTC m=+584636.565108778"
  }
}

Campaign Ended Callback

{
  "accountName": "1223334444-123455",
  "type": "campaignEnded",
  "campaignEnded": {
    "softwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae"
  }
}

About Callback Services

About Software Management Services API Callback Notifications

Overview

Subscribing to Callback Services

Callback Security

Callback JSON Schema

JSON Schema Reference for OMA-DM and LWM2M Devices using the /v1 Resource Path

Calback Parameter Definitions

Example Callback

JSON Schema Reference for HTTP Devices using the /v2 Resource Path

V2 Callback Parameter Definitions

Example Callback

New software Callback

Campaign Queued Callback

Campaign Request Failed Callback

Campaign Scheduled Callback

Campaign Aborted Callback

Campaign Canceled Callback

Campaign Ended Callback