About Software Management Services API Callback Notifications

Overview

The ThingSpace firmware Management Services API can use a callback service (webhook) to send messages to your application when new firmware 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 is currently be on the device to upgrade.
toVersion string The firmware version that the device will be upgraded to.
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 Callbacks

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",
  "firmwareList": [
    {
      "firmwareName": "string",
      "model": "string",
      "make": "string",
      "protocol": "string",
      "firmwareFrom": "string",
      "firmwareTo": "string",
      "launchDate": "string",
      "releaseNote": "string",
      "devicePlatformId": "string"
    }
  ],
  "campaignRequestQueued": {
    "firmwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "schedStatus": "string"
  },
  "campaignRequestFailed": {
    "firmwareName": "string",
    "campaignId": "string",
    "resultCode": "string",
    "resultReason": "string",
    "requestFailedDate": "string"
  },
  "campaignScheduled": {
    "firmwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "schedStatus": "string",
    "resultCode": "string",
    "resultReason": "string"
  },
  "campaignAborted": {
    "firmwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "resultCode": "string",
    "resultReason": "string",
    "abortedTime": "string"
  },
  "campaignCanceled": {
    "firmwareName": "string",
    "campaignId": "string",
    "resultCode": "string",
    "resultReason": "string",
     "canceledTime": "string"
  },
  "campaignEnded": {
    "firmwareName": "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.
firmwareList array  
  firmwareName string The name of the firmware.
  model string The device model that the firmware applies to.
  make string The device make that the firmware applies to.
  protocol string Valid values include: LWM2M, OMA, HTTP
  firmwareFrom string The name of the old firmware on the device.
  firmwareTo string The name of the firmware you are upgrading to.
  launchDate string($date-time) The firmware launch date.
  releaseNote string firmware release note.
  devicePlatformId string The platform (Android, iOS, for example) that the firmware can be applied to.
CampaignRequestQueued array  
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
  startDate string($date-time) Campaign start date.
  schedStatus string Status of the campaign. "CampaignRequestQueued."
campaignRequestFailed array  
  firmwareName string The name of the firmware.
  campaignId string Firmware 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  
  firmwareName string The name of the firmware.
  campaignId string Firmware 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  
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
  startDate string($date-time) 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  
  firmwareName string The name of the firmware.
  campaignId string Firmware 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($date-time) The date the campaign ended.
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled

Example Callbacks

New firmware Callback

{
  "accountName":"1223334444-12345",
  "type":"newFirmware",
  "firmwareList": [
    {
      "firmwareName":"FOTA_Verizon_Model-A_01To02_HF",
      "model":"Model-A",
      "make": "Verizon",
      "distributionType": "HTTP",
      "firmwareFrom":"VerizonFirmwareVersion-01",
      "firmwareTo":"VerizonFirmwareVersion-02"
      "launchDate":"2017-11-08 20:15:42.738 +0000 UTC",
      "releaseNote":"",
      "devicePlatformId": "IoT"
    }
  ]
}

Campaign Queued Callback

{
  "accountName":"1223334444-12345",
  "type":"campaignReqeustQueued",
   "campaignRequestQueued": {
    "firmwareName": "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": {
    "firmwareName": "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": {
    "firmwareName": "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": {
    "firmwareName": "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": {
    "firmwareName": "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": {
    "firmwareName": "FOTA_Verizon_Model-A_01To02_HF",
    "campaignId": "f9ce4356-0812-4ae3-86ff-e34e46d11fae"
  }
}

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

{
  "accountName": "string",
  "participantName": "string",
  "type": "string",
  "firmwareList": [
    {
      "firmwareName": "string",
      "model": "string",
      "make": "string",
      "distributionType": "string",
      "firmwareFrom": "string",
      "firmwareTo": "string",
      "launchDate": "string",
      "releaseNote": "string",
      "devicePlatformId": "string"
    }
  ],
  "campaignRequestQueued": {
    "firmwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "schedStatus": "string"
  },
  "campaignRequestFailed": {
    "firmwareName": "string",
    "campaignId": "string",
    "resultCode": "string",
    "resultReason": "string",
    "requestFailedDate": "string"
  },
  "campaignScheduled": {
    "firmwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "schedStatus": "string",
    "resultCode": "string",
    "resultReason": "string"
  },
  "campaignPreScheduled": {
    "firmwareName": "string",
    "campaignId": "string",
    "startDate": "string",
    "resultCode": "string",
    "resultReason": "string"
  },
  "campaignCanceled": {
    "firmwareName": "string",
    "campaignId": "string",
    "resultCode": "string",
    "resultReason": "string",
     "canceledTime": "string"
  },
  "campaignEnded": {
    "firmwareName": "string",
    "campaignId": "string
  }
}

V3 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.
firmwareList array  
  firmwareName string The name of the firmware.
  model string The device model that the firmware applies to.
  make string The device make that the firmware applies to.
  protocol string Valid values include: LWM2M, OMA, HTTP
  firmwareFrom string The name of the old firmware on the device.
  firmwareTo string The name of the firmware you are upgrading to.
  launchDate string($date-time) The firmware launch date.
  releaseNote string Firmware release note.
CampaignRequestQueued array  
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
  startDate string($date-time) Campaign start date.
  schedStatus string Status of the campaign. "CampaignRequestQueued."
campaignRequestFailed array  
  firmwareName string The name of the firmware.
  campaignId string Firmware 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  
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
  startDate string($date-time) Campaign start date.
  schedStatus string CampaignScheduled
  resultCode string Schedule Success
  resultReason string Additional notes about the resultCode
campaignPreScheduled array  
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled
  startDate string($date-time) Campaign start date.
  resultCode string Schedule aborted.
  resultReason string Additional notes about the resultCode
campaignCanceled array  
  firmwareName string The name of the firmware.
  campaignId string Firmware 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($date-time) The date the campaign ended.
  firmwareName string The name of the firmware.
  campaignId string Firmware upgrade identifier, returned in the “id” value of the POST /{campaigns}/acc response when the upgrade was scheduled

Example Callbacks

Campaign queued

{
  "accountName": "2123334444-55345",
  "type": "campaignRequestQueued",
  "campaignRequestQueued": {
    "firmwareName": "FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE",
    "campaignId": "21746bb4-0123-11ec-8dc9-8eafe9447c26",
    "startDate": "2021-08-19",
    "schedStatus": "CampaignRequestQueued"
  }
}

Campaign pre-scheduled

{
  "accountName": "2123334444-55345",
  "type": "campaignPreScheduled",
  "campaignPreScheduled": {
    "firmwareName": "FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE",
    "campaignId": "21746bb4-0123-11ec-8dc9-8eafe9447c26",
    "startDate": "2021-08-19 00:00:00 +0000 UTC",
    "schedStatus": "CampaignPreScheduled",
    "resultCode": "Request for SCEF data Success",
    "resultReason": "Successfully requested for SCEF data"
  }
}

Campaign scheduled

{
  "accountName": "2123334444-55345",
  "type": "campaignScheduled",
  "campaignScheduled": {
    "firmwareName": "FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE",
    "campaignId": "21746bb4-0123-11ec-8dc9-8eafe9447c26",
    "startDate": "2021-08-19 00:00:00 +0000 UTC",
    "schedStatus": "CampaignScheduled",
    "resultCode": "Schedule Success",
    "resultReason": "Successfully scheduled campaign"
  }
}

Campaign ended

{
  "accountName": "2123334444-55345",
  "type": "campaignEnded",
  "campaignEnded": {
    "firmwareName": "FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE",
    "campaignId": "21746bb4-0123-11ec-8dc9-8eafe9447c26"
  }
}

Campaign failure

{
  "accountName": "2123334444-55345",
  "type": "campaignFailed",
  "campaignFailed": {
    "firmwareName": "FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE",
    "campaignId": "50ca15f9-011f-11ec-9f40-b66c7bf9e5d1",
    "resultCode": "Schedule Failed",
    "resultReason": "Upgrade failed, all attempts are exhausted",
    "canceledTime": "2021-08-21 00:00:36.936024375 +0000 UTC m=+104982.789134163"
  }
}

New firmware available

{
  "accountName": "2123334444-55345",
  "type": "newFirmware",
  "firmwareList": [
    {
      "firmwareName": "FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE",
      "launchDate": "0001-01-01 00:00:00 +0000 UTC",
      "releaseNote": "[ FOTA_Verizon_Model-A_01To02_HF_LW_MOTIVE ] VerizonFirmwareVersion-01 of the Verizon/Model-A needs to be upgraded to VerizonFirmwareVersion-02.",
      "model": "Model-A",
      "make": "Verizon",
      "fromVersion": "VerizonFirmwareVersion-01",
      "toVersion": "VerizonFirmwareVersion-02",
      "clientType": "LWM2M"
    },
    {
      "firmwareName": "FOTA_Verizon_Model-A_100To01_HF_OMA_MOTIVE",
      "launchDate": "0001-01-01 00:00:00 +0000 UTC",
      "releaseNote": "[ FOTA_Verizon_Model-A_100To01_HF_OMA_MOTIVE ] VerizonFirmwareVersion-100 of the Verizon/Model-A needs to be upgraded to VerizonFirmwareVersion-01.",
      "model": "Model-A",
      "make": "Verizon",
      "fromVersion": "VerizonFirmwareVersion-100",
      "toVersion": "VerizonFirmwareVersion-01",
      "clientType": "OMADM"
    }
  ]
}