Azure IoT Hub non-telemetry event schemas
This article provides the properties and schemas for non-telemetry events emitted by Azure IoT Hub. Non-telemetry events are different from device-to-cloud and cloud-to-device messages in that IoT Hub emits these events in response to specific state changes associated with your devices. For example, lifecycle changes like a device or module being created or deleted, or connection state changes like a device or module connecting or disconnecting.
You can route non-telemetry events using message routing, or reach to non-telemetry events using Azure Event Grid. To learn more about IoT Hub message routing, see IoT Hub message routing and React to IoT Hub events by using Event Grid.
The event examples in this article were captured using the az iot hub monitor-events
Azure CLI command. You may see a subset of properties included in the events that arrive at a message routing endpoint.
Available event types
Azure IoT Hub emits the non-telemetry events in the following categories:
Event category | Description |
---|---|
Device connection state events | Emitted when a device connects to or disconnects from an IoT hub. |
Device lifecycle events | Emitted when a device or module is created on or deleted from an IoT hub. |
Device twin change events | Emitted when a device or module twin is changed or replaced. |
Digital twin change events | Emitted when a device or module's digital twin is changed or replaced. |
Common event properties
Non-telemetry events share several common properties.
System properties
IoT Hub sets the following system properties on each event.
Property | Type | Description | Keyword for routing query |
---|---|---|---|
content-encoding | string | utf-8 | $contentEncoding |
content-type | string | application/json | $contentType |
correlation-id | string | A unique ID that identifies the event. | $correlationId |
user-id | string | The name of IoT Hub that generated the event. | $userId |
iothub-connection-device-id | string | The device ID. | $connectionDeviceId |
iothub-connection-module-id | string | The module ID. This property is output only for module life cycle and twin events. | $connectionModuleId |
iothub-enqueuedtime | number | Date and time when the notification was sent. In routing queries, use an ISO8601 timestamp; for example, $enqueuedTime > "2022-06-06T22:56:06Z" |
$enqueuedTime |
iothub-message-source | string | The event category that identifies the message source. For example, deviceLifecycleEvents. | N/A |
Application properties
IoT Hub sets the following application properties on each event.
Property | Type | Description |
---|---|---|
deviceId | string | The device ID. |
hubName | string | The name of the IoT Hub that generated the event. |
iothub-message-schema | string | The message schema associated with the event category; for example, deviceLifecycleNotification. |
moduleId | string | The module ID. This property is output only for module lifecycle and twin change events. |
operationTimestamp | string | The ISO8601 timestamp of the operation. |
opType | string | The identifier for the operation that generated the event. For example, createDeviceIdentity or deleteDeviceIdentity. |
In routing queries, use the property name. For example, deviceId = "my-device"
.
Connection state events
Connection state events are emitted whenever a device or module connects or disconnects from the IoT hub.
Application properties: The following table shows how application properties are set for connection state events:
Property | Value |
---|---|
iothub-message-schema | deviceConnectionStateNotification |
opType | deviceConnected or deviceDisconnected |
Both modules and devices use the deviceConnected
and deviceDisconnected
application properties to report connection state events. If the event came from a module, then the event also includes a moduleId
property. If there is no moduleId
property, then the event came from a device.
System properties: The following table shows how system properties are set for connection state events:
Property | Value |
---|---|
iothub-message-source | deviceConnectionStateEvents |
Body: The body contains a sequence number. The sequence number is a string representation of a hexadecimal number. You can use string compare to identify the larger number. If you're converting the string to hex, then the number will be a 256-bit number. The sequence number is strictly increasing, so the latest event has a higher number than older events. This is useful if you have frequent device connects and disconnects, and want to ensure that only the latest event is used to trigger a downstream action.
Example
The following JSON shows a device connection state event emitted when a device disconnects.
{
"event": {
"origin": "contoso-device-1",
"module": "",
"interface": "",
"component": "",
"properties": {
"system": {
"content_encoding": "utf-8",
"content_type": "application/json",
"correlation_id": "aaaa0000-bb11-2222-33cc-444444dddddd",
"user_id": "contoso-routing-hub"
},
"application": {
"hubName": "contoso-routing-hub",
"deviceId": "contoso-device-1",
"opType": "deviceDisconnected",
"iothub-message-schema": "deviceConnectionStateNotification",
"operationTimestamp": "2022-06-01T18:43:04.5561024Z"
}
},
"annotations": {
"iothub-connection-device-id": "contoso-device-1",
"iothub-enqueuedtime": 1654109018051,
"iothub-message-source": "deviceConnectionStateEvents",
"x-opt-sequence-number": 72,
"x-opt-offset": "37344",
"x-opt-enqueued-time": 1654109018176
},
"payload": {
"sequenceNumber": "000000000000000001D8713FF7E0851400000002000000000000000000000007"
}
}
}
Device lifecycle events
Device lifecycle events are emitted whenever a device or module is created or deleted from the identity registry. For more detail about when device lifecycle events are generated, see Device and module lifecycle notifications.
Application properties: The following table shows how application properties are set for device lifecycle events:
Property | Value |
---|---|
iothub-message-schema | deviceLifecycleNotification |
opType | One of the following values: createDeviceIdentity, deleteDeviceIdentity, createModuleIdentity, or deleteModuleIdentity. |
System properties: The following table shows how system properties are set for device lifecycle events:
Property | Value |
---|---|
iothub-message-source | deviceLifecycleEvents |
Body: The body contains a representation of the device twin or module twin. It includes the device ID and module ID, the twin etag, the version property, and the tags, properties, and associated metadata of the twin.
Example
The following JSON shows a device lifecycle event emitted when a module is created. The event is captured using the az iot hub monitor-events
Azure CLI command.
{
"event": {
"origin": "contoso-device-2",
"module": "module-1",
"interface": "",
"component": "",
"properties": {
"system": {
"content_encoding": "utf-8",
"content_type": "application/json",
"correlation_id": "c5a4e6986c",
"user_id": "contoso-routing-hub"
},
"application": {
"hubName": "contoso-routing-hub",
"deviceId": "contoso-device-2",
"operationTimestamp": "2022-05-27T18:49:38.4904785Z",
"moduleId": "module-1",
"opType": "createModuleIdentity",
"iothub-message-schema": "moduleLifecycleNotification"
}
},
"annotations": {
"iothub-connection-device-id": "contoso-device-2",
"iothub-connection-module-id": "module-1",
"iothub-enqueuedtime": 1653677378534,
"iothub-message-source": "deviceLifecycleEvents",
"x-opt-sequence-number": 62,
"x-opt-offset": "31768",
"x-opt-enqueued-time": 1653677378643
},
"payload": {
"deviceId": "contoso-device-2",
"moduleId": "module-1",
"etag": "AAAAAAAAAAE=",
"version": 2,
"properties": {
"desired": {
"$metadata": {
"$lastUpdated": "0001-01-01T00:00:00Z"
},
"$version": 1
},
"reported": {
"$metadata": {
"$lastUpdated": "0001-01-01T00:00:00Z"
},
"$version": 1
}
}
}
}
}
Device twin change events
Device twin change events are emitted whenever a device twin or a module twin is updated or replaced. In some cases, several changes may be packaged in a single event. To learn more, see Device twin backend operations or Module twin backend operations.
Application properties: The following table shows how application properties are set for device twin change events:
Property | Value |
---|---|
iothub-message-schema | twinChangeNotification |
opType | One of the following values: replaceTwin or updateTwin. |
System properties: The following table shows how system properties are set for device twin change events:
Property | Value |
---|---|
iothub-message-source | twinChangeEvents |
Body: On an update, the body contains the version property of the twin and the updated tags and properties and their associated metadata. On a replace, the body contains the device ID and module ID, the twin etag, the version property, and all the tags, properties, and associated metadata of the device or module twin.
Example
The following JSON shows a twin change event emitted for an update of a desired property and a tag on a module twin. The event is captured using the az iot hub monitor-events
Azure CLI command.
{
"event": {
"origin": "contoso-device-3",
"module": "module-1",
"interface": "",
"component": "",
"properties": {
"system": {
"content_encoding": "utf-8",
"content_type": "application/json",
"correlation_id": "4d1f1e2e74f",
"user_id": "contoso-routing-hub"
},
"application": {
"hubName": "contoso-routing-hub",
"deviceId": "contoso-device-3",
"operationTimestamp": "2022-06-01T22:27:50.2612586Z",
"moduleId": "module-1",
"iothub-message-schema": "twinChangeNotification",
"opType": "updateTwin"
}
},
"annotations": {
"iothub-connection-device-id": "contoso-device-3",
"iothub-connection-module-id": "module-1",
"iothub-enqueuedtime": 1654122470282,
"iothub-message-source": "twinChangeEvents",
"x-opt-sequence-number": 17,
"x-opt-offset": "12352",
"x-opt-enqueued-time": 1654122470329
},
"payload": {
"version": 7,
"tags": {
"tag1": "new value"
},
"properties": {
"desired": {
"property1": "new value",
"$metadata": {
"$lastUpdated": "2022-06-01T22:27:50.2612586Z",
"$lastUpdatedVersion": 6,
"property1": {
"$lastUpdated": "2022-06-01T22:27:50.2612586Z",
"$lastUpdatedVersion": 6
}
},
"$version": 6
}
}
}
}
}
Next steps
To learn about message routing, see IoT Hub message routing.
To learn how to add queries to your message routes, see IoT Hub message routing query syntax.
To learn about the structure of device-to-cloud and cloud-to-device messages, see Create and read IoT Hub messages.