Connecting Azure IoT Hub to UniAsset

Overview

Azure IoT Hub is Microsoft's cloud-scale message broker for IoT devices. UniAsset's IoT Signal ingestion endpoint accepts the telemetry that IoT Hub forwards, recording every signal against the asset it belongs to.

This article walks through:

1. The prerequisites
2. Creating an API key in UniAsset
3. Configuring an Azure IoT Hub message route
4. The payload format UniAsset expects
5. Verifying signals are arriving
6. Troubleshooting common errors

Requirements

• Available on: Odyssey, Cosmos
• Roles: Owner, to create the API key

Important UniAsset stores and displays signals. Nothing reacts to them automatically — a signal does not raise a work order, open an incident, or send an alert. Keep threshold logic in Azure and treat UniAsset as the record it writes to.

Prerequisites

Before you begin, confirm you have:

• A UniAsset organization on Odyssey or Cosmos
• The Owner role in UniAsset (required to create integration API keys)
• An active Azure subscription with an Azure IoT Hub instance
• Permission in Azure to add a custom endpoint to IoT Hub and to create a message route
• HTTPS connectivity from Azure to https://<your-uniasset-domain>

Step 1 — Create a UniAsset API key

1. Sign in to UniAsset as the Owner.
2. Go to Settings → Integrations → API Keys.
3. Click New API Key.
4. Give it a descriptive name (for example, Azure IoT Hub — Production).
5. Grant only the iot:signal:ingest permission. Do not add write permissions this integration does not need.
6. Create it. The full key is shown once — copy it now and store it in Azure Key Vault. UniAsset stores only a short lookup prefix and a hash, so the key cannot be recovered afterwards.

The key format is ua_live_ followed by 64 characters.

See How to create API keys for the full reference.

Step 2 — Add UniAsset as a custom endpoint in Azure IoT Hub

In the Azure portal:

1. Open your IoT Hub instance.
2. Under Hub settings, select Message routing.
3. Switch to the Custom endpoints tab and click + Add → Webhook.
4. Name the endpoint UniAsset.
5. Set the URI to https://<your-uniasset-domain>/api/integrations/iot/signals.
6. Under Custom headers, add:
   • Authorization: Bearer ua_live_<your-key>
   • Content-Type: application/json
7. Save the endpoint.

Step 3 — Create the message route

1. In Message routing, switch to the Routes tab and click + Add.
2. Name the route forward-to-uniasset.
3. Data source: Device Telemetry Messages.
4. Endpoint: the UniAsset endpoint you just created.
5. Routing query: leave as true to forward everything, or scope it (for example, signalType = 'temperature.high') if your devices already emit a signalType property.
6. Save.

Step 4 — Shape the payload

UniAsset expects each signal as a JSON object with at least source, signalType, and payload. Devices that emit raw sensor messages should transform them either at the edge or via an Azure Function bridge.

{
  "assetId": "ckxyz123abc",
  "deviceId": "azure-device-001",
  "source": "AzureIoTHub",
  "signalType": "temperature.high",
  "severity": "HIGH",
  "numericValue": 92.5,
  "payload": {
    "temperature": 92.5,
    "unit": "C",
    "messageId": "12fa..."
  }
}

Edge transformation with an Azure Function

If your devices emit a raw schema, the simplest pattern is an HTTP-triggered Azure Function that receives the IoT Hub message, transforms it, and POSTs to UniAsset. A starting point:

export async function azureIoTBridge(req: { body: any }) {
  const raw = req.body;
  const uniassetPayload = {
    deviceId: raw.systemProperties["iothub-connection-device-id"],
    source: "AzureIoTHub",
    signalType: raw.properties.signalType ?? "telemetry.raw",
    severity: raw.properties.severity,
    numericValue: raw.body.value,
    payload: raw.body,
  };

  await fetch("https://<your-uniasset-domain>/api/integrations/iot/signals", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.UNIASSET_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify(uniassetPayload),
  });
}

Step 5 — Verify signals are arriving

1. In UniAsset, go to Dashboard → IoT Signals (visible on Odyssey and above).
2. The timeline should show messages within seconds of devices publishing.
3. If you mapped assetId, open the corresponding asset in Assets → <name> and scroll to the IoT Signals section.

Best practices

• Store the API key in Azure Key Vault. Do not check it into source control or paste it into the IoT Hub UI without a Key Vault reference.
• Use one API key per environment. Production and staging should have distinct keys so revocation is surgical.
• Adopt a dotted-path signalType convention. It future-proofs rule patterns: temperature.high, temperature.low, vibration.spike, door.open, motor.runtime.
• Send severities as upper case enums — CRITICAL, HIGH, MEDIUM, LOW, INFO. UniAsset normalizes anything else, but consistency makes the signal list easier to read and filter.
• Keep payloads under 1 MB. UniAsset rejects larger bodies with a 413 PAYLOAD_TOO_LARGE. For aggregate uploads, split at the IoT Hub side.

Troubleshooting

Related articles

• Understanding IoT signals
• Managing connected industrial assets
• How to create API keys
• Getting started with the REST API
• API Security