Azure IoT Hub as an Event Grid source
This article provides the properties and schema for Azure IoT Hub events. For an introduction to event schemas, see Azure Event Grid event schema.
Available event types
Azure IoT Hub emits the following event types:
Event type | Description |
---|---|
Microsoft.Devices.DeviceCreated | Published when a device is registered to an IoT hub. |
Microsoft.Devices.DeviceDeleted | Published when a device is deleted from an IoT hub. |
Microsoft.Devices.DeviceConnected | Published when a device is connected to an IoT hub. |
Microsoft.Devices.DeviceDisconnected | Published when a device is disconnected from an IoT hub. |
Microsoft.Devices.DeviceTelemetry | Published when a telemetry message is sent to an IoT hub. |
Example event
The schemas for DeviceConnected and DeviceDisconnected events have the same structure. This sample event shows the schema of an event raised when a device is connected to an IoT hub:
[{
"id": "f6bbf8f4-d365-520d-a878-17bf7238abd8",
"source": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
"subject": "devices/LogicAppTestDevice",
"type": "Microsoft.Devices.DeviceConnected",
"time": "2018-06-02T19:17:44.4383997Z",
"data": {
"deviceConnectionStateEventInfo": {
"sequenceNumber":
"000000000000000001D4132452F67CE200000002000000000000000000000001"
},
"hubName": "egtesthub1",
"deviceId": "LogicAppTestDevice",
"moduleId" : "DeviceModuleID"
},
"specversion": "1.0"
}]
The DeviceTelemetry event is raised when a telemetry event is sent to an IoT Hub. A sample schema for this event is shown below.
[{
"id": "9af86784-8d40-fe2g-8b2a-bab65e106785",
"source": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
"subject": "devices/LogicAppTestDevice",
"type": "Microsoft.Devices.DeviceTelemetry",
"time": "2019-01-07T20:58:30.48Z",
"data": {
"body": {
"Weather": {
"Temperature": 900
},
"Location": "USA"
},
"properties": {
"Status": "Active"
},
"systemProperties": {
"iothub-content-type": "application/json",
"iothub-content-encoding": "utf-8",
"iothub-connection-device-id": "d1",
"iothub-connection-auth-method": "{\"scope\":\"device\",\"type\":\"sas\",\"issuer\":\"iothub\",\"acceptingIpFilterRule\":null}",
"iothub-connection-auth-generation-id": "123455432199234570",
"iothub-enqueuedtime": "2019-01-07T20:58:30.48Z",
"iothub-message-source": "Telemetry"
}
},
"specversion": "1.0"
}]
The schemas for DeviceCreated and DeviceDeleted events have the same structure. This sample event shows the schema of an event raised when a device is registered to an IoT hub:
[{
"id": "56afc886-767b-d359-d59e-0da7877166b2",
"source": "/SUBSCRIPTIONS/<subscription ID>/RESOURCEGROUPS/<resource group name>/PROVIDERS/MICROSOFT.DEVICES/IOTHUBS/<hub name>",
"subject": "devices/LogicAppTestDevice",
"type": "Microsoft.Devices.DeviceCreated",
"time": "2018-01-02T19:17:44.4383997Z",
"data": {
"twin": {
"deviceId": "LogicAppTestDevice",
"etag": "AAAAAAAAAAE=",
"deviceEtag": "null",
"status": "enabled",
"statusUpdateTime": "0001-01-01T00:00:00",
"connectionState": "Disconnected",
"lastActivityTime": "0001-01-01T00:00:00",
"cloudToDeviceMessageCount": 0,
"authenticationType": "sas",
"x509Thumbprint": {
"primaryThumbprint": null,
"secondaryThumbprint": null
},
"version": 2,
"properties": {
"desired": {
"$metadata": {
"$lastUpdated": "2018-01-02T19:17:44.4383997Z"
},
"$version": 1
},
"reported": {
"$metadata": {
"$lastUpdated": "2018-01-02T19:17:44.4383997Z"
},
"$version": 1
}
}
},
"hubName": "egtesthub1",
"deviceId": "LogicAppTestDevice"
},
"specversion": "1.0"
}]
Event properties
All events contain the same top-level data:
Property | Type | Description |
---|---|---|
id |
string | Unique identifier for the event. |
source |
string | Full resource path to the event source. This field isn't writeable. Event Grid provides this value. |
subject |
string | Publisher-defined path to the event subject. |
type |
string | One of the registered event types for this event source. |
time |
string | The time the event is generated based on the provider's UTC time. |
data |
object | IoT Hub event data. |
specversion |
string | CloudEvents schema specification version. |
For all IoT Hub events, the data object contains the following properties:
Property | Type | Description |
---|---|---|
hubName |
string | Name of the IoT Hub where the device was created or deleted. |
deviceId |
string | The unique identifier of the device. This case-sensitive string can be up to 128 characters long, and supports ASCII 7-bit alphanumeric characters plus the following special characters: - : . + % _ # * ? ! ( ) , = @ ; $ ' . |
The contents of the data object are different for each event publisher.
For Device Connected and Device Disconnected IoT Hub events, the data object contains the following properties:
Property | Type | Description |
---|---|---|
moduleId |
string | The unique identifier of the module. This field is output only for module devices. This case-sensitive string can be up to 128 characters long, and supports ASCII 7-bit alphanumeric characters plus the following special characters: - : . + % _ # * ? ! ( ) , = @ ; $ ' . |
deviceConnectionStateEventInfo |
object | Device connection state event information |
sequenceNumber |
string | A number which helps indicate order of device connected or device disconnected events. Latest event will have a sequence number that is higher than the previous event. This number may change by more than 1, but is strictly increasing. See how to use sequence number. |
For Device Telemetry IoT Hub event, the data object contains the device-to-cloud message in IoT hub message format and has the following properties:
Property | Type | Description |
---|---|---|
body |
string | The content of the message from the device. |
properties |
string | Application properties are user-defined strings that can be added to the message. These fields are optional. |
system properties |
string | System properties help identify contents and source of the messages. Device telemetry message must be in a valid JSON format with the contentType set to JSON and contentEncoding set to UTF-8 in the message system properties. If this isn't set, then IoT Hub will write the messages in base 64 encoded format. |
For Device Created and Device Deleted IoT Hub events, the data object contains the following properties:
Property | Type | Description |
---|---|---|
twin |
object | Information about the device twin, which is the cloud representation of application device metadata. |
deviceID |
string | The unique identifier of the device twin. |
etag |
string | A validator for ensuring consistency of updates to a device twin. Each etag is guaranteed to be unique per device twin. |
deviceEtag |
string | A validator for ensuring consistency of updates to a device registry. Each deviceEtag is guaranteed to be unique per device registry. |
status |
string | Indicates whether the device twin is enabled or disabled. |
statusUpdateTime |
string | The ISO8601 timestamp of the last device twin status update. |
connectionState |
string | Indicates whether the device is connected or disconnected. |
lastActivityTime |
string | The ISO8601 timestamp of the last activity. |
cloudToDeviceMessageCount |
integer | Count of cloud to device messages sent to this device. |
authenticationType |
string | Authentication type used for this device: either SAS , SelfSigned , or CertificateAuthority . |
x509Thumbprint |
string | The thumbprint is a unique value for the x509 certificate, commonly used to find a particular certificate in a certificate store. The thumbprint is dynamically generated using the SHA1 algorithm, and doesn't physically exist in the certificate. |
primaryThumbprint |
string | Primary thumbprint for the x509 certificate. |
secondaryThumbprint |
string | Secondary thumbprint for the x509 certificate. |
version |
integer | An integer that is incremented by one each time the device twin is updated. |
desired |
object | A portion of the properties that can be written only by the application back-end, and read by the device. |
reported |
object | A portion of the properties that can be written only by the device, and read by the application back-end. |
lastUpdated |
string | The ISO8601 timestamp of the last device twin property update. |
Tutorials and how-tos
Title | Description |
---|---|
Send email notifications about Azure IoT Hub events using Logic Apps | A logic app sends a notification email every time a device is added to your IoT Hub. |
React to IoT Hub events by using Event Grid to trigger actions | Overview of integrating IoT Hub with Event Grid. |
Order device connected and device disconnected events | Shows how to order device connection state events. |
Next steps
- For an introduction to Azure Event Grid, see What is Event Grid?
- To learn about how IoT Hub and Event Grid work together, see React to IoT Hub events by using Event Grid to trigger actions.