Callback notifications for resources and lifecycle events

The callback notification API allows the client application to receive the following information from IMPACT IoT:
  • Operations on resources
  • Life cycle events
  • Observed resources

IMPACT IoT sends the requested information in the form of asynchronous notifications on the callback URL of the client application.

Callback notifications describes the structure of the callback notification API.

Table 1. Callback notifications
Title Callback notifications
URL https://<netApp_callback_url>
Method POST
Content-Type application/json
URL Params None
Data Params

The following are the data parameters:

  • serialNumber:[string]: Specifies the unique endpoint ID of the device.

  • timestamp:[integer]: Specifies the IMPACT IoT processing time (number of milliseconds since 1970).

  • subscriptionId:[string]: Specifies the subscription correlator generated by IMPACT IoT on acknowledgement of the subscription request.

  • resourcePath:[string]: Specifies the path of the resource observed within the scope of a subscription. This parameter is mandatory inside a resources element.

    The resourcePath is obtained in case of data policy notification. For example, Time resource has the value sent by the device which is appended with three zeroes.

    Example: resourcePath":"3/0/13",*"value":"1543422580000""

  • value:[string]: Specifies the payload of the resource subject to observation (base64-encoded in case of binary content).

  • make:[string]: Specifies the name of the device manufacturer.

  • model:[string]: Specifies the device model.

  • firmwareVersion:[string]: Specifies the current firmware version of the device.

  • groupName:[string]: Specifies the IMPACT IoT group to which the device pertains to.

  • imsi:[string]: Specifies the IMSI of the device.

  • address:[string]: Specifies the address of the device.

  • freeFormAddress:[string]: Specifies the free form address or identifier of the device.

  • tags:[string]: Specifies the list of device tags.

  • requestId:[string]: Specifies the request correlator as generated by IMPACT IoT on acknowledgement of the request.

  • creationDate:[string]: Specifies the date on which the device was created (registered) on the system.

  • resources:[composite]: Specifies the list of resources supported by the device with current known values or resources requested within the scope of a READ command.

    None in case of Write, Delete, and Execute commands, as these operations do not return any resource value.

  • result:[complex]: Specifies the final result codes and reason of request on device ( READ, Write, Delete, and Execute).

  • code:[ string]: Specifies the main result code of the original request or operation, set by IMPACT IoT system. Valid values are:
    • 0 - Success
    • 1 - Failure
    • 2 - Warning
  • subCode:[string]: Specifies the result code specified by the device protocol. In case of internal error, it specifies the result code generated by IMPACT IoT. Value of the subCode depends on the device protocol, hence it is protocol specific. Default value of subCode if 0, if undetermined.

  • reason:[string]: Specifies the error message.

Callback Response Status Code The following are the callback response status codes:
  • 200 - Callback notification is posted successfully
  • 400, 401, 413, 429, 500, 503 - Callback notification will be retried till the maximum retry attempts are reached.
  • All other 4xx and 5xx - Callback notification is considered as failed.
Sample Call Curl:
curl -X POST --header 'Content-Type: application/json' --header 'Accept: application/json' --header 'Authorization: Basic YXJhdmludGg6VGVzdEAxMjM=' -d '{"reports":[{"serialNumber":"352253064335283","timestamp":1485339813341,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/batteryVoltage","value":"12.6"},{"serialNumber":"352253064335283","timestamp":1485339813347,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"location/0/latitude","value":"13.78631"},{"serialNumber":"352253064335283","timestamp":1485339813356,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"location/0/longitude","value":"100.54647"},{"serialNumber":"352253064335283","timestamp":1485339813377,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/rpm","value":"0.0"},{"serialNumber":"352253064335283","timestamp":1485339813397,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/speed","value":"0.0"},{"serialNumber":"352253064335283","timestamp":1485339813417,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/milesTravelled","value":"1015.0"},{"serialNumber":"352253064335283","timestamp":1485339813438,"subscriptionId":"e7a570f4-a175-4f2a-8080-d44400065ada","resourcePath":"vehicle/0/fuelLevel","value":"0.0"}],"registrations":[],"deregistrations":[],"updates":[],"expirations":[],"responses":[]}' '<http://CallbackURL>'
Notes None

Controlling the payload size

IMPACT IoT allows controlling the payload size for the Application callback notifications. The payload size is set at a system level and can be overridden by the Application at registration.

For controlling the payload size at the user level, the user can configure the payload size at the time of registration using the registration API using the optional payloadSize field, in Bytes.

For example:

PUT /m2m/applications/registration HTTP/1.1
Host: devlwm2m-edge-01
Authorization: Basic ZHRhZzpkdGFn
Content-Type: application/json
Content-Length: 153

{"authorization": "Basic ZGVtbzpkZW1v"}
"url": "",
"payloadSize": 40000

Oversized uplink payloads

In cases where the payload cannot be segmented, for example, due to a large single encrypted uplink packet, the application may receive a payload greater than the maximum payload size.

Precendence order

The payload size from the API (user level) will get precedence over the system level limit. If the payloadSize is not provided for a user, IMPACT IoT will use the system level value for the user.

Sample for subscription failure

If an Application has requested a subscription which has failed for some reason, then this will be detailed to the Application. An example of this occurring is when an attempt to create a LWM2M observation fails.

Following is a sample subscription failure notification: