Azure Event Hub Integration

Azure Event Hub Integration reads events from an Azure Event Hubs event hub, typically the built-in Event Hub-compatible endpoint of Azure IoT Hub. An uplink data converter transforms each event into device or asset data, including telemetry and attributes. For IoT Hub, ThingsBoard can also send downlink cloud-to-device messages to any device in the hub.

Use Azure Event Hub Integration when:

• Your devices already send device-to-cloud messages to Azure IoT Hub, and you want their telemetry in ThingsBoard.
• Your applications publish events to an Azure event hub.
• You need to send commands from ThingsBoard to IoT Hub devices as cloud-to-device messages.

1. Receive data. Devices send device-to-cloud messages to IoT Hub, which routes them to its built-in Event Hub-compatible endpoint. The integration reads every partition of that endpoint as a member of a consumer group.
2. Decode the payload. The uplink converter identifies the target device or asset from the payload and extracts attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard can create an entity that does not exist yet.
4. Send downlink data (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and the integration sends it through the IoT Hub service API as a cloud-to-device message to the device in metadata.deviceId.

• Access to ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• An Azure account with an active subscription and permission to create an IoT hub and register devices.
• The Azure CLI with the azure-iot extension to send test messages.
• Outbound TCP ports 5671 (AMQP) and 443 open from the ThingsBoard server to Azure.

Create the hub, register a device, and copy the connection details of the built-in endpoint.

1. In the Azure portal, click + Create a resource, search for IoT Hub, and click Create.
2. On the Basics tab, select or create a Resource group and enter a globally unique IoT hub name, for example thingsboard-integration.
3. Click Review + create, then Create.
4. When the deployment finishes, click Go to resource.

The Basic tier does not support cloud-to-device messages. For downlink, choose the Free or Standard tier. For tiers and limits, see Create an IoT hub.

Click Create a resource Search for IoT Hub Click Create Set the resource group and hub name, then click Review + create Review the settings and click Create Wait for the deployment to finish Click Go to resource

This guide registers a device with the ID 8F4A2C6D, the same ID the sample payload carries. The ThingsBoard device then has the same name as its Azure device, so downlinks reach it without extra mapping.

1. In the hub, go to Device management ⇾ Devices and click + Add device.
2. Enter the Device ID 8F4A2C6D.
3. Keep Authentication type set to Symmetric key and Auto-generate keys selected.
4. Click Save.

Open the devices page of the hub Click + Add device Enter the Device ID and click Save The device appears in the list with status Enabled

1. In the hub, go to Hub settings ⇾ Built-in endpoints.
2. Under Event Hub compatible endpoint, copy the Event Hub-compatible endpoint. It is a connection string that ends in EntityPath=<event hub name>.
3. Optional: under Consumer Groups, add a consumer group for ThingsBoard, for example thingsboard. Do this if another application already reads the endpoint with $Default.

Open Built-in endpoints Copy the Event Hub-compatible endpoint

The Shared access policy above the endpoint selects the key in the connection string. ThingsBoard reuses this key for downlinks, so keep a policy with Service connect permission, such as iothubowner or service.

To read a standalone event hub instead, copy the connection string of a shared access policy on that event hub. It also ends in EntityPath=<event hub name>. Downlink is not available in this case.

You now have the values for the integration:

Create the uplink converter, assign it to a new Azure Event Hub integration, and send a test message.

The uplink converter receives each event body as a byte array, resolves the target device, and returns its telemetry and attributes. Azure Event Hub Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

This guide uses the sample payload that ThingsBoard provides for Azure Event Hub converters, with a recent timestamp:

{
  "deviceId": "8F4A2C6D",
  "deviceType": "Packing machine",
  "temperature": 25.5,
  "pressure": 1013.25,
  "vibration": {
    "x": 0.02,
    "y": 0.03,
    "z": 0.015
  },
  "location": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10
  },
  "timestamp": "2026-10-14T10:30:00Z",
  "status": "ALARM",
  "alarms": [
    {
      "type": "temperature",
      "severity": "high",
      "message": "Temperature exceeds threshold."
    },
    {
      "type": "vibration",
      "severity": "critical",
      "message": "Excessive vibration detected."
    }
  ],
  "metadata": {
    "version": 1,
    "batteryLevel": 100,
    "batteryStatus": "Charging",
    "manufacturer": "Example corporation"
  }
}

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select Azure Event Hub.

4. Name — enter a name, for example Azure Event Hub Uplink Converter.

5. Main decoding configuration — the editor opens with the default Azure Event Hub template. Replace it with the decoder below. The decoder maps measurements and state to telemetry and static device properties to attributes. It also reads timestamp, location, and vibration when the payload carries them. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   var data = decodeToJson(payload);
   
   var deviceName = data.deviceId != null ? data.deviceId : "Device A";
   var deviceType = data.deviceType != null ? data.deviceType : "default";
   
   // ISO 8601 timestamp; fall back to server time.
   var ts = data.timestamp != null ? new Date(data.timestamp).getTime() : Date.now();
   
   // Static device properties become attributes.
   var attributes = {};
   if (data.location != null) {
       attributes.latitude = data.location.latitude;
       attributes.longitude = data.location.longitude;
       attributes.altitude = data.location.altitude;
   }
   

   ▼Expand

   To adapt:

   • Device name in another field — replace data.deviceId, for example with data.serialNumber.
   • Device name of the sender — for IoT Hub messages, use the Azure Device ID of the sender: metadata["sysProp:iothub-connection-device-id"].
   • Optional fields — remove the location, vibration, status, or alarms mappings your devices never send.
   • Other telemetry — add keys to telemetry, for example humidity: data.humidity.
   • Other device properties — add them to attributes, for example model: data.model.
   • Update-only keys — for Azure Event Hub, ThingsBoard pre-fills the Update only keys list in Advanced decoding parameters with manufacturer, receivedAlarms, status, batteryLevel, batteryStatus, and version. These keys are stored only when their value changes. Edit the list to match your keys.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

Built-in helpers:

For field renaming, nested values, and non-JSON payloads, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. Replace the content of Payload with the sample payload. Click Test. The Output panel shows:

{
  "deviceName": "8F4A2C6D",
  "deviceType": "Packing machine",
  "attributes": {
    "latitude": 37.7749,
    "longitude": -122.4194,
    "altitude": 10,
    "version": 1,
    "manufacturer": "Example corporation"
  },
  "telemetry": {
    "ts": 1791973800000,
    "values": {
      "temperature": 25.5,
      "pressure": 1013.25,
      "status": "ALARM",
      "receivedAlarms": [
        {
          "type": "temperature",
          "severity": "high",
          "message": "Temperature exceeds threshold."
        },
        {
          "type": "vibration",
          "severity": "critical",
          "message": "Excessive vibration detected."
        }
      ],
      "vibrationX": 0.02,
      "vibrationY": 0.03,
      "vibrationZ": 0.015,
      "batteryLevel": 100,
      "batteryStatus": "Charging"
    }
  }
}

ts is the payload’s timestamp, 2026-10-14T10:30:00Z, in milliseconds.

Check that deviceName is set and telemetry holds the expected keys. If the output is empty or shows an error, fix the decoder and test again.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select Azure Event Hub.
   • Name — keep the default or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose Azure Event Hub Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to send cloud-to-device messages.
5. Connection:
   • Connection string — paste the Event Hub-compatible endpoint.
   • Consumer group — in Advanced settings, enter thingsboard if you created it. Otherwise, leave it empty to use $Default.
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Click Check connection. ThingsBoard connects to the endpoint and lists its partitions.
7. Click Add.

Advanced settings

A checkpoint records the last event the integration processed in each partition. Without persistent checkpoints, the integration keeps them in memory, and events sent while it is stopped are skipped. With persistent checkpoints, it stores them in an Azure Blob Storage container and processes those events after a restart, as long as the hub still retains them.

1. In the Azure portal, open a storage account, or create one.
2. Go to Security + networking ⇾ Access keys and copy the Connection string of key1.
3. In the integration, turn on Enable persistent checkpoints.
4. Paste the connection string into Storage connection string.
5. Enter a Container name, for example eventhubcontainer. The integration creates the container if it does not exist.

Open the storage account Existing containers are listed under Data storage ⇾ Containers Copy the connection string of key1

With persistent checkpoints on, Check connection also checks access to the container.

Send a device-to-cloud message as device 8F4A2C6D, then confirm that ThingsBoard decoded it and created the device.

The integration reads only events that arrive after it starts, so add the integration first. Send the sample payload without timestamp. The decoder then uses the current server time; with a fixed timestamp, the data would fall outside the recent time windows of your dashboards as time passes.

az iot device send-d2c-message \
  --hub-name thingsboard-integration \
  --device-id 8F4A2C6D \
  --data '{"deviceId":"8F4A2C6D","deviceType":"Packing machine","temperature":25.5,"pressure":1013.25,"vibration":{"x":0.02,"y":0.03,"z":0.015},"location":{"latitude":37.7749,"longitude":-122.4194,"altitude":10},"status":"ALARM","alarms":[{"type":"temperature","severity":"high","message":"Temperature exceeds threshold."},{"type":"vibration","severity":"critical","message":"Excessive vibration detected."}],"metadata":{"version":1,"batteryLevel":100,"batteryStatus":"Charging","manufacturer":"Example corporation"}}'

The command sends the message as the device, the same way device firmware does.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK. Click ⋅⋅⋅ in the Message column to see the event: systemProperties and payload.
• Converter events — open Azure Event Hub Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the received payload, Out shows the decoded result, and Metadata shows the sysProp: values and the integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created 8F4A2C6D with the Packing machine profile. Open it and check the Latest telemetry tab for temperature, pressure, status, receivedAlarms, vibrationX–vibrationZ, batteryLevel, and batteryStatus, and the Attributes tab for latitude, longitude, altitude, version, and manufacturer.

ThingsBoard sends a downlink when the Rule Engine routes a message to the integration — for example, after a shared attribute update. The integration sends it through the IoT Hub service API as a cloud-to-device message to the Azure device in metadata.deviceId. IoT Hub queues the message until the device receives it or the message expires.

Downlink requires:

• An IoT hub as the event source. A standalone event hub has no cloud-to-device messaging.
• IoT Hub Name in the integration.
• A Connection string whose policy has Service connect permission.

The downlink converter turns a Rule Engine message into the message body. For the full encoder reference, see Downlink data converter.

The encoder returns:

• contentType — JSON, TEXT, or BINARY.
• data — the message body.
• metadata — deviceId, the Azure Device ID of the target device. Required: without it, the integration skips the message. Every metadata key is also added to the message properties, together with content-type.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and Azure Event Hub integration type are preselected.
3. Enter a name, for example Azure Event Hub Downlink Converter.
4. In Main encoding configuration, replace the default encoder with the one below.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add.
7. Enter the IoT Hub Name, for example thingsboard-integration. The field becomes required once a downlink converter is assigned.
8. Click Apply changes.

Encoder used in this guide (TBEL and JavaScript):

/** Encoder **/

// Send the Rule Engine message as the message body.
var result = {
  // Payload content type: JSON, TEXT, or BINARY (Base64).
  contentType: 'JSON',
  data: JSON.stringify(msg),
  metadata: {
    // Azure Device ID of the target device.
    // This guide uses the same ID as the ThingsBoard device name.
    deviceId: metadata.deviceName
  }
};

return result;

To check the encoder, click Test encoder function. Message type is already ATTRIBUTES_UPDATED. Set Message to {"temperatureUploadFrequency":60} and deviceName in Metadata to 8F4A2C6D, if they differ, then click Test. The Output shows:

{
  "contentType": "JSON",
  "data": "{\"temperatureUploadFrequency\":60}",
  "metadata": {
    "deviceId": "8F4A2C6D"
  }
}

To adapt:

• Another envelope — build data in the structure your device firmware expects, for example { "method": "setConfig", "params": msg }.
• Different Azure Device IDs — when ThingsBoard device names differ from Azure Device IDs, store the Azure ID in a device attribute and read it into metadata with an enrichment node.
• Message properties — add keys to metadata, for example source: 'thingsboard'. The device receives them as message properties.
• Other message types — branch on msgType, for example to handle RPC_CALL_FROM_SERVER_TO_DEVICE with msg.method and msg.params. See Rule Engine message types.

The encoder reads deviceName from the message metadata, so the rule chain first adds the device name.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Enrichment section, drag an originator fields node onto the canvas.
3. Enter a Name (for example, Retrieve device name) and map the source fields:
   • Name ⇾ deviceName
   • Add mapped originator fields to ⇾ Metadata
   • Click Add.
4. Connect the message type switch node to the originator fields node with the Attributes Updated relation.
5. From the Action section, drag an integration downlink node onto the canvas.
6. Enter a Name (for example, Downlink to Azure Event Hub), select your Azure Event Hub integration, and click Add.
7. Connect the originator fields node to the integration downlink node with the Success relation.
8. Click Apply changes.

1. Go to Devices & assets ⇾ Devices, select 8F4A2C6D, and open the Attributes tab.
2. Select Shared attributes and click +.
3. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add. ThingsBoard sends the downlink.

• Integration events — the integration’s Events tab shows a Downlink event with deviceId, payload ({"temperatureUploadFrequency":60}), and properties.

• Azure portal — in the hub, go to Device management ⇾ Devices. The Cloud to Device Message Count of 8F4A2C6D has increased.

• Device side — receive the message as the device:

  az iot device c2d-message receive --hub-name thingsboard-integration --device-id 8F4A2C6D

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Azure IoT Hub Integration — connect to IoT Hub over MQTT as one device.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• Downlink data converter — encoder reference.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• IoT Hub built-in endpoint — Event Hub-compatible endpoint, consumer groups, and retention.
• Cloud-to-device messages — delivery, expiration, and feedback.