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.

Tip

• Messages are delivered at least once. You should deduplicate on your end using the hashId field.
• New properties may be added to any object in the JSON message without a version change. Make sure your parser does not reject messages with unknown properties.

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)

Reconstructing the numeric value

The actual numeric value can be reconstructed as significand * 10^orderOfMagnitude. For example, a significand of 7827 with an order of magnitude of 3 represents 7,827,000. The formattedValue field provides a pre-formatted string for display purposes.

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