The new version of our Incoming Webhook is currently in preview.

This guide is designed to help developers integrate their devices with EnergyID using webhooks. Webhooks allow your devices to send measurement data directly to EnergyID.

Here's a step-by-step explanation on how to use the EnergyID webhooks:

1. Provisioning Credentials: Generate a provisioning key and secret, which are stored on the device. Multiple devices can use the same provisioning credentials as long as all devices within the same provisioning fleet have a unique identifier.

2. Device Provisioning: The device contacts EnergyID at the endpoint https://hooks.energyid.eu/hello using the provisioning key and secret, along with its unique identifier.

   • Device Registration: If the device is not yet registered with EnergyID, the /hello endpoint will return a WebhookClaimInfo object containing a claim code and URL. This URL should be displayed on the device’s configuration page, allowing the user to click on it and link the device to their EnergyID record.

   • Data Hub Information: Once the device has been claimed, the /hello endpoint will return a WebhookConnectionInfo object. This contains the webhook URL, the required HTTP headers (including an authorization token), and the allowed upload interval for sending data to the EnergyID Data Hub.
3. Sending Data: Once the device has access to the Data Hub, it can start sending measurement data to the provided webhook URL. Make sure to include the required HTTP headers in each request.

Updating Connection Information: The authorization token included in the connection information is valid for 48 hours and must be refreshed regularly. We recommend polling the /hello endpoint every 24 hours to renew the token and check for any changes in webhook policy.
If the device receives an HTTP 401 response when sending data, this indicates that the token has expired and should be renewed immediately.

Device Provisioning

Endpoint:

POST https://hooks.energyid.eu/hello

Headers:

• X-Provisioning-Key: Your provisioning key.
• X-Provisioning-Secret: Your provisioning secret.

Perameters:

• deviceId: Unique identifier (within the app fleet) for the device
• deviceName: Human readable device name.
• firmwareVersion (optional): Firmware version.
• ipAddress (optional): Local IP address.
• macAddress (optional): MAC address.
• localDeviceUrl (optional): URL for device configuration in the local network.

Example

POST https://hooks.energyid.eu/hello

{
  "deviceId": "<DEVICE_ID>",
  "deviceName": "My device"
}

Claim response

{
  "claimCode": "4H7A70",
  "claimUrl": "https://app.energyid.eu/integrations/webhook-in/new?code=4H7A70",
  "exp": 1691402519
}

Data-hub information response

{
  "webhookUrl": "https://hooks.energyid.eu/webhook-in",
  "headers": {
    "authorization": "Bearer <jwt>",
    "x-twin-id": "00000000-0000-0000-0000-000000000000"
  },
  "webhookPolicy": {
    "uploadInterval": 60,
  }
}

Sending Data

Once the device receives a webhook URL, it can start sending data. To do this, send a POST request to the webhook URL and include all headers returned during the device provisioning process.

Data should be sent in a simple key-value JSON object. The ts key, which represents the timestamp of the measurements as a Unix timestamp (in seconds), is the only required key. Other keys represent the ID of a specific metric or sensor measured by the device and their corresponding values. Some keys are predefined by EnergyID, as described in the list below. You can choose other keys, but since EnergyID does not know what these data points represent, the user will need to specify this information before the data becomes visible in EnergyID. Predefined keys can also be used as prefixes (separated by a period) when multiple data points of the same type are present. Data can be sent either as a single object or as a list of objects.

Example

POST <webhook URL>

{
  "ts": 1733835004,
  "gas": 1594.78,
  "pv": 35461.45,
  "el.t1": 11250,
  "el-i.t1": 1545,
  "el.t2": 8944,
  "el-i.t2": 6577,
  "my-custom-sensor": 544.22
}

Predefined Properties