Message Routing

Message routing enables you to automatically direct device telemetry, twin changes, and lifecycle events to one or more custom endpoints without writing any code on the device side.

On this page

Overview
Routing endpoints
Routing query language
End‑to‑end example
FAQ

Overview

Azure IoT Hub can evaluate each incoming message against a set of routing rules. When a rule matches, the message is forwarded to the specified endpoint(s). This feature reduces latency, off‑loads processing from downstream services, and provides a clean separation of concerns.

Routing endpoints

Supported built‑in and custom endpoints include:

Endpoint type	Description
Event Hub (built‑in)	High‑throughput ingestion to downstream analytics.
Service Bus Queue	Reliable point‑to‑point messaging.
Service Bus Topic	Publish/subscribe pattern for multiple consumers.
Azure Storage (Blob/Queue/Table)	Persist raw messages for later batch processing.
Azure Functions	Serverless processing with custom logic.
Custom Webhook	HTTP callbacks to external systems.

Routing query language

Routing rules use a SQL‑like syntax to filter messages based on system and custom properties.

SELECT * FROM /messages WHERE temperature > 30 AND humidity < 50

Common system properties:

messageId
correlationId
contentType
connectionDeviceId
connectionDeviceGenerationId
iothub-connection-auth-method

Custom application properties are accessed as properties.<name>.

SELECT * FROM /messages WHERE properties.alert = 'critical'

End‑to‑end example

This example creates a routing rule that forwards all temperature events above 30°C to an Azure Function named TemperatureAlert.

Create the Azure Function endpoint:

az iot hub routing-endpoint create \
    --hub-name MyIoTHub \
    --endpoint-name TemperatureAlert \
    --endpoint-type AzureFunction \
    --resource-group MyResourceGroup \
    --function-app MyFunctionApp \
    --function-name TemperatureAlert

Define the routing rule:

az iot hub routing-rule create \
    --hub-name MyIoTHub \
    --name HighTempRule \
    --source devicemessages \
    --endpoint-name TemperatureAlert \
    --condition "temperature > 30"

Verify the rule:

az iot hub routing-rule show \
    --hub-name MyIoTHub \
    --name HighTempRule

FAQ

Can I route twin change events?

Yes. Use source = twinchangeevents when creating a routing rule.

What is the maximum number of routing rules per hub?

The limit is 100 routing rules per IoT Hub (standard tier). Higher tiers allow more.

How are message properties encoded?

System properties are automatically added by IoT Hub. Application properties can be set by the device using JSON payload or MQTT user properties.