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.
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.
To increase security when receiving callback messages from ThingSpace, you can implement these protocols:
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.
{
"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"
}
]
}
}
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 |
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"
}
}
{
"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
}
}
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 |
{
"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"
}
]
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"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"
}
}
{
"accountName": "1223334444-123455",
"type": "campaignEnded",
"campaignEnded": {
"softwareName": "FOTA_Verizon_Model-A_01To02_HF",
"campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae"
}
}