Azure Event Hubs trigger node
Azure Event Hubs Trigger Node
Overview
The Azure Event Hubs Trigger Node automatically initiates MaestroHub pipelines when events arrive on an event hub. Unlike the Event Hubs Send connector node which sends events within an already-running pipeline, the Event Hubs Trigger starts new pipeline executions in response to incoming events—enabling fully event-driven stream processing.
Core Functionality
What It Does
Event Hubs Trigger enables real-time, event-driven pipeline execution by:
1. Event-Driven Pipeline Execution Start pipelines automatically when events arrive on an event hub, without manual intervention or polling. Ideal for stream processing, event-driven microservices, and real-time data ingestion.
2. Partition-Aware Consumer Groups
Uses a partition-aware EventProcessor with the connection's consumer group. With an Azure Blob checkpoint store, multiple pipeline instances load-balance the hub's partitions between them for parallel processing and fault tolerance.
3. Event Payload and Metadata Passthrough
Incoming event payloads along with metadata (partition ID, offset, sequence number, partition key, enqueued time) are passed directly to the pipeline, making them available to all downstream nodes via the $node and $trigger variables.
Configuration Options
Basic Information
| Field | Type | Description |
|---|---|---|
| Node Label | String (Required) | Display name for the node on the pipeline canvas |
| Description | String (Optional) | Explains what this trigger initiates |
Parameters
| Parameter | Type | Default | Required | Constraints | Description |
|---|---|---|---|---|---|
| Connection ID | string | "" | Yes | -- | Azure Event Hubs connection profile to use. |
| Function ID | string | "" | Yes | -- | Consume function within the connection. Only Consume functions are listed. |
| Trigger Mode | select | "always" | No | always / onChange | always: Trigger on every event. onChange: Only trigger when the payload differs from the last received value for that partition. |
| Enabled | boolean | true | No | -- | Enable/disable the trigger. When disabled, no events are consumed from the hub. |
The selected function must be an Azure Event Hubs Consume function type. Send, Send Batch, Get Partitions, and List Consumer Groups functions cannot be used with Event Hubs Trigger nodes.
Settings
Description
A free-text area for documenting the node's purpose and behavior. Notes entered here are saved with the pipeline and visible to all team members.
Execution Settings
| Setting | Options | Default | Description |
|---|---|---|---|
| Timeout (seconds) | number | Pipeline default | Maximum execution time for this node (1–600). Leave empty for pipeline default. |
| Retry on Timeout | Pipeline Default / Enabled / Disabled | Pipeline Default | Whether to retry the node if it times out. |
| Retry on Fail | Pipeline Default / Enabled / Disabled | Pipeline Default | Whether to retry on failure. When Enabled, shows Advanced Retry Configuration. |
| On Error | Pipeline Default / Stop Pipeline / Continue Execution | Pipeline Default | Behavior when node fails after all retries. |
Advanced Retry Configuration (visible when Retry on Fail = Enabled)
| Field | Type | Default | Range | Description |
|---|---|---|---|---|
| Max Attempts | number | 3 | 1–10 | Maximum retry attempts. |
| Initial Delay (ms) | number | 1000 | 100–30,000 | Wait before first retry. |
| Max Delay (ms) | number | 120000 | 1,000–300,000 | Upper bound for backoff delay. |
| Multiplier | number | 2.0 | 1.0–5.0 | Exponential backoff multiplier. |
| Jitter Factor | number | 0.1 | 0–0.5 | Random jitter (+-percentage). |
Output Data Structure
When an Event Hubs event triggers pipeline execution, the following data is available to downstream nodes via the $trigger variable.
Output Format
{
"_metadata": {
"type": "azureeventhubs_trigger",
"partitionId": "0",
"offset": "12345",
"sequenceNumber": "87",
"partitionKey": "line-3",
"enqueuedTime": "2026-09-05T14:47:19.123Z",
"protocol": "azureeventhubs",
"connectionId": "bf29be94-fc0a-4dc4-8e5c-092f1b74eb4b",
"functionId": "aef374c3-aa2b-454e-aabc-5657faac5950",
"timestamp": "2026-09-05T14:47:19.123Z"
},
"result": {
"deviceId": "line-3",
"temperature": 21.5
}
}
Accessing Event Data
In downstream nodes, use the $trigger variable to access the trigger output:
| Field | Expression | Description |
|---|---|---|
| Event Payload | $trigger.result | The event body. Valid JSON is delivered parsed — an object, array, number or string — so $trigger.result.<field> reads a field directly. Anything that is not valid JSON is delivered as a string |
| Partition | $trigger._metadata.partitionId | The partition the event was read from |
| Offset | $trigger._metadata.offset | The event's offset in that partition |
| Sequence Number | $trigger._metadata.sequenceNumber | The event's sequence number in the partition |
| Partition Key | $trigger._metadata.partitionKey | The partition key the producer sent — present only when one was set |
| Enqueued Time | $trigger._metadata.enqueuedTime | When Event Hubs accepted the event (RFC 3339, UTC) |
| Protocol | $trigger._metadata.protocol | Always azureeventhubs |
| Connection ID | $trigger._metadata.connectionId | The connection profile the trigger runs on |
| Function ID | $trigger._metadata.functionId | The subscribe function that received the message |
| Trigger Type | $trigger._metadata.type | Always azureeventhubs_trigger |
| Timestamp | $trigger._metadata.timestamp | When MaestroHub received the message (RFC 3339, UTC) |
Every _metadata value is a string — "3", not 3; "false", not false — so compare them as strings. The message itself keeps its JSON types:
$trigger.result.deviceId— a field of a JSON event$trigger.result— the whole event
Validation Rules
The Azure Event Hubs Trigger Node enforces these validation requirements:
Parameter Validation
Connection ID
- Must be provided and non-empty
- Must reference a valid Azure Event Hubs connection profile
- Error: "Azure Event Hubs connection is required"
Function ID
- Must be provided and non-empty
- Must reference a valid Azure Event Hubs Consume function
- Function must belong to the specified connection
- Error: "Consume function is required"
Enabled Flag
- Must be a boolean if provided
- Error: "Enabled must be a boolean value"
Consumption and Checkpointing
The trigger's consumer position is tracked by the connection's checkpoint store:
- In-memory checkpoint store: partition offsets are lost on restart, and only one instance may consume (no cross-instance coordination). Suitable for testing and single-instance deployments.
- Azure Blob checkpoint store: offsets are committed durably. Multiple instances load-balance partitions and resume from the last committed offset after a restart — required to scale the trigger out.
The consume function's Start Position (latest or earliest) only applies to partitions that have no checkpoint yet; once offsets are committed, consumption resumes from the last committed position.
Usage Examples
Stream Processing Pipeline
Scenario: Consume raw sensor events from an event hub, enrich them with asset metadata, and send processed results to a downstream hub.
Configuration:
- Label: Sensor Event Processor
- Connection: Production Event Hubs
- Function: Consume from
telemetry(consumer group:sensor-enrichment) - Trigger Mode: always
- Enabled: true
Downstream Processing:
- Parse JSON payload to extract sensor readings
- Enrich with asset metadata from a MongoDB lookup
- Apply data quality validations
- Send enriched events to a
processed-telemetryhub
Real-Time UNS Ingestion
Scenario: Ingest device events published to Event Hubs by an Azure-native gateway and publish them into the Unified Namespace.
Configuration:
- Label: Device Event Ingestor
- Connection: IoT Event Hubs
- Function: Consume from
device-events(consumer group:uns-ingest) - Trigger Mode: always
- Enabled: true
Downstream Processing:
- Map the event payload to a UNS topic path
- Publish to the UNS
- Log ingest results for an audit trail
Deduplicated Event Processing
Scenario: Process equipment status updates from Event Hubs but only trigger pipeline execution when the status actually changes, reducing unnecessary processing.
Configuration:
- Label: Equipment Status Monitor
- Connection: Factory Event Hubs
- Function: Consume from
equipment-status(consumer group:status-monitor) - Trigger Mode: onChange
- Enabled: true
Downstream Processing:
- Extract equipment ID and new status from the payload
- Update equipment state in MongoDB
- Send a notification via MS Teams for critical status changes
- Log state transitions for historical analysis