Forwarding to an HTTPS endpoint

Messages are forwarded to an HTTPS endpoint by issuing a request to a destination of your choice. For most authentication methods the request uses the POST method. When the destination is Amazon S3 or Azure Blob Storage the method changes to PUT and a date-based object path is appended to the URL (see below). The body of these requests is JSON encoded and includes a Content-Type: application/json header. Depending on the authentication method configured, additional headers may be present. The body is a JSON array that can include one or more messages.

The platform supports the following authentication methods:

Static header — a secret token is placed in a configurable header (e.g. Authorization)
OAuth2 Client Credentials — the platform exchanges client credentials for a bearer token, which is cached and refreshed automatically. Two sub-modes are supported:
- Secret in body — the client_id and client_secret are sent as URL-encoded form parameters in the POST body to the token endpoint.
- Secret in header — only grant_type=client_credentials is sent in the POST body; the credentials are passed as a Basic Authorization header to the token endpoint.
AWS Signature V4 — requests are signed using AWS SigV4, supporting direct delivery to services like Amazon S3. For S3 destinations the method is PUT and the URL is extended with {YYYY}/{MM}/{DD}/{timestamp}.
Azure Shared Access Signature — supports Azure Blob Storage and Azure Event Hubs. For Blob Storage destinations the method is PUT and the URL is extended with {YYYY}/{MM}/{DD}/{timestamp}.json. For Event Hubs the method remains POST.

Measurement messages

When a report is processed, the platform forwards a measurement message containing the report data and its observations. Each observation represents an individual measurement for a specific quantity and port.

All internal IDs are encoded as hash IDs. Numeric values are represented using a significand and order of magnitude pair, alongside a pre-formatted human-readable string.

[
  {
    "hashId": "qoa978",
    "environmentHashId": "f1a4w1",
    "connectivityEnvironmentReportTypeHashId": "y124as",
    "monitoringEnvironmentReportTypeHashId": "l19a7s",
    "observations": [
      {
        "connectivityEnvironmentQuantityHashId": "sajia1",
        "monitoringEnvironmentQuantityHashId": "sajia1",
        "portHashId": "e13d57",
        "channelIndex": 0,
        "orderOfMagnitude": 3,
        "significand": 7827,
        "formattedValue": "7,827,000",
        "unit": "W",
        "generatedAt": "2023-01-01T00:00:00.000Z",
        "performance": 1
      },
      {
        "connectivityEnvironmentQuantityHashId": "sajia1",
        "monitoringEnvironmentQuantityHashId": "sajia1",
        "portHashId": "e13d57",
        "channelIndex": 1,
        "orderOfMagnitude": 0,
        "significand": 23041,
        "formattedValue": "230.41",
        "unit": "V",
        "generatedAt": "2023-01-01T00:00:00.000Z",
        "performance": 1
      }
    ],
    "deviceHashId": "j1iha9",
    "deviceIdentifier": "device-serial-12345",
    "deviceFields": {
      "brand": "ExampleBrand",
      "model": "X100"
    },
    "fields": {
      "firmware": "v2.1.0"
    },
    "locationHashId": "dao97",
    "locationFields": {
      "site": "Amsterdam-North"
    },
    "userHashId": null,
    "generatedAt": "2023-01-01T00:00:00.000Z",
    "createdAt": "2023-01-01T00:00:01.000Z",
    "attempt": 0
  }
]

Field reference

| Field | Type | Description | |---|---|---| | hashId | string | Unique report identifier | | environmentHashId | string | Unique environment identifier (monitoring or connectivity) | | connectivityEnvironmentReportTypeHashId | string \| null | Unique connectivity environment report type identifier | | monitoringEnvironmentReportTypeHashId | string \| null | Unique monitoring environment report type identifier | | observations | Measurement[] | Array of individual measurements (see below) | | deviceHashId | string \| null | Unique device identifier | | deviceIdentifier | string \| null | Supplier device identifier | | deviceFields | object | Arbitrary key-value pairs from the device configuration | | fields | object | Arbitrary key-value pairs from the event/report | | locationHashId | string \| null | Unique location identifier | | locationFields | object | Arbitrary key-value pairs from the location | | userHashId | string \| null | Unique user identifier (null for device-generated reports) | | generatedAt | string | ISO 8601 timestamp of when the report was generated | | createdAt | string | ISO 8601 timestamp of when the report was stored in the platform | | attempt | integer | 0-indexed delivery attempt number |

Measurement observation fields

| Field | Type | Description | |---|---|---| | connectivityEnvironmentQuantityHashId | string \| null | Unique connectivity environment quantity identifier | | monitoringEnvironmentQuantityHashId | string \| null | Unique monitoring environment quantity identifier | | portHashId | string \| null | Unique port identifier | | channelIndex | integer \| null | Channel index | | orderOfMagnitude | integer | Order of magnitude of the value | | significand | integer | Significand of the value | | formattedValue | string | Human-readable formatted value | | unit | string \| null | Unit of the quantity (e.g. "W", "V", "A") | | generatedAt | string | ISO 8601 timestamp of when the measurement was taken | | performance | number | Performance indicator (1 = normal, 0 = no measurement) |

Notification messages

When a device or quantity is added, updated, or deleted, the platform forwards a notification message. This allows downstream systems to stay in sync with configuration changes.

[
  {
    "hashId": "qoa978",
    "environmentHashId": "f1a4w1",
    "observations": [
      {
        "hashId": "dfa1p",
        "object": "device",
        "action": "add",
        "device": {
          "identifier": "device-serial-12345"
        },
        "createdAt": "2023-01-01T00:00:00.000Z",
        "updatedAt": "2023-01-01T00:00:00.000Z",
        "deletedAt": null
      },
      {
        "hashId": "dfa1p",
        "object": "quantity",
        "action": "update",
        "quantity": {
          "name": {
            "en": "Active Power",
            "nl": "Actief vermogen"
          }
        },
        "createdAt": "2023-01-01T00:00:00.000Z",
        "updatedAt": "2023-01-02T12:00:00.000Z",
        "deletedAt": null
      }
    ],
    "generatedAt": "2023-01-01T00:00:00.000Z",
    "attempt": 0
  }
]

Field reference

| Field | Type | Description | |---|---|---| | hashId | string | Identifier of the notification event that triggered this batch | | environmentHashId | string | Unique environment identifier (monitoring or connectivity) | | observations | Notification[] | Array of individual notifications (see below) | | generatedAt | string | ISO 8601 timestamp of when the notification batch was generated | | attempt | integer | 0-indexed delivery attempt number |

Notification observation fields

| Field | Type | Description | |---|---|---| | hashId | string | Unique notification identifier | | object | string | The object type that changed: "device" or "quantity" | | action | string | The action performed: "add", "update", or "delete" | | device | object \| undefined | Present when object is "device". Contains identifier (supplier device identifier, can be null) | | quantity | object \| undefined | Present when object is "quantity". Contains name (translations object with language keys like en, nl) | | createdAt | string | ISO 8601 timestamp of when the notification was created | | updatedAt | string | ISO 8601 timestamp of when the notification was last updated | | deletedAt | string \| null | ISO 8601 timestamp of when the object was deleted, or null |