Webhooks

Our webhooks can be used to alert and monitor a household's energy consumption. One can set up two different webhook notifications:

• addEstimatedHourlyActiveEnergyLimitWarningAlertSetting: A dynamic alert that continuously evaluates whether the device has crossed a set limit for energy consumption within the hour.
• addHourlyConsumptionLimitEstimationWarningAlertSetting: An alert that is evaluated 30 minutes into the hour and checks if the device's energy consumption is about to exceed a set limit.

Setting up webhook settings

setIntermediaryWebhookSetting - here you must enter a secret which you must use to verify the data you receive from us. You only need to do this once.

Testing webhook settings

testWebhookSetting can be called after the webhook is configured. This must contain the callbackUrl to which the webhook will be sent. We then send the following data:

{
  "event": "webhook:test"
}

You can use this to test that the setup is correct.

Create alert settings

Alerts are created in the API with addHourlyConsumptionLimitEstimationWarningAlertSetting or addEstimatedHourlyActiveEnergyLimitWarningAlertSetting.

Furthermore, you must add a NotificationChannel, this is done using addIntermediaryWebhookNotificationChannelToAlertSetting. This is where we send the alert you are configuring.

Receive webhooks

The signature you must verify data against is sent in X-Ecomon-Signature. Data for consumption alerts will typically be something like this:

{
  "data": {
    "alerts": [
      {
        "configuredLimitInWatts": 1000,
        "consumptionThisFarInTheCurrentHourInWatts": 800,
        "deviceId": "device_1"
      },
      {
        "configuredLimitInWatts": 1000,
        "consumptionThisFarInTheCurrentHourInWatts": 501,
        "deviceId": "device_2"
      }
    ]
  },
  "event": "HOURLY_CONSUMPTION_LIMIT_ESTIMATION_WARNING"
}

Example: Verify data integrity

The data is hashed with sha1 and the secret you provide when you create the webhook. To verify the integrity, you perform the same operation on the data on your side with the secret you provided when you created the webhook setting.

Javascript / Typescript (Node)

Here is an example of how to find the signature in Node:

  export const _getSha1SignatureForData = ({
    data,
    secret,
  }: {
    data: WebhookData;
    secret: string;
  }): string => {
    const stringifiedData = JSON.stringify(data);

    const hmac = crypto.createHmac("sha1", secret);
    const signature = Buffer.from(
      "sha1=" + hmac.update(stringifiedData).digest("hex"),
      "utf8"
    );

    return signature.toString();
  };

Python

Here is an example of how to find the signature in Python:

import hashlib
import hmac
import json

def get_signature(secret, data):
    stringified_data = json.dumps(data, separators=(',', ':'))
    hmac_obj = hmac.new(secret.encode('utf-8'), stringified_data.encode('utf-8'), hashlib.sha1)
    signature = "sha1=" + hmac_obj.hexdigest()
    return signature

Update alerts

You can update the alert, like setting the limit for triggering an alert, with the API mutations updateEstimatedHourlyActiveEnergyLimitWarningAlertSetting or updateHourlyConsumptionLimitEstimationWarningAlertSetting.