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.

   • Webhook 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 EnergyID.
     • The uploadInterval is a value in seconds and depends on the user's EnergyID subscription plan:
       • Free: 86400 seconds (24 hours)
       • Premium: 900 seconds (15 minutes)
       • Real-time Add-on: 60 seconds
3. Sending Data: Once the device has access to the webhook, 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.

Parameters:

• 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": "",
  "deviceName": "My device"
}

Claim response

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

Webhook information response

{
  "webhookUrl": "https://hooks.energyid.eu/webhook-in",
  "headers": {
    "authorization": "Bearer ",
    "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.

When using these predefined properties (like 'gas', 'pv', 'el'), EnergyID automatically recognizes the type of meter or sensor they represent, so data sent with these keys will be immediately visible and properly categorized without additional configuration.

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

{
  "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

Error Handling

It is best practice to prepare for scenarios where attempts to send a payload might fail. Incoming webhooks may return errors for malformed requests, invalid credentials, or when something exceptional prevents us from storing your data.

Rate Limiting

The API enforces rate limits to ensure fair usage. If your device sends too many requests in a short period, the server will respond with an HTTP 429 Too Many Requests error.

When this happens, check the Retry-After HTTP header in the response. This header contains the number of seconds you should wait before making another request. To avoid hitting this limit, it is good practice to bundle data and run your process less frequently, for instance, every 15 minutes. Although staying above the allowed interval should be fine. For a good example you can see here how we bundle and send data in batches.

Building Apps

Hardware suppliers and cloud-to-cloud data providers can feature their own integration in the EnergyID App Directory. This allows for a more streamlined user experience.

Instead of using standard user-level credentials, partners receive a dedicated Device Provisioning Key and Secret. These are linked to a dedicated endpoint for your application, providing a robust and scalable solution for your users. Contact us at info@energieid.be for more information on becoming an integration partner.