Skip to main content

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 using

  • addHourlyConsumptionLimitEstimationWarningAlertSetting
  • addEstimatedHourlyActiveEnergyLimitWarningAlertSetting
  • addSustainableConsumptionAlertSetting.

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

The newer SUSTAINABLE_CONSUMPTION_ALERT will have a structure like this

{
  "data": {
    "alerts": [
      {
        "alertSettingId": "alert_12345",
        "deviceId": "device_1",
        "intermediaryId": "intermediary_789",
        "appliesToHour": "2025-04-15T14:00:00Z",
        "evaluatedAt": "2025-04-15T14:30:00Z",
        "consumed": { "value": 2000, "unit": "WattHour" },
        "forecasted": { "value": 4500, "unit": "WattHour" },
        "hourlyTotal": { "value": 4000, "unit": "WattHour" },
        "hourlyLimit": { "value": 5000, "unit": "WattHour" },
        "message": "Energy consumption is sustainable. It is predicted to remain under the defined limit for the current hour.",
        "type": "SUSTAINABLE"
      }
    ]
  }
  "event": "event:sustainable_consumption"
}

To properly handle SUSTAINABLE_CONSUMPTION_ALERT, ensure your system recognizes the following TypeScript interfaces:

interface WebhookData {
  alertSettingId: string;
  deviceId: string;
  intermediaryId: string;
  metadata?: Record<string, unknown>;
  appliesToHour: Date;
  evaluatedAt: Date;
  consumed: Energy;
  forecasted: Energy;
  hourlyTotal: Energy;
  hourlyLimit: Energy;
  message: string;
  type: EventType;
}

type EnergyUnit = "WattHour";

type Energy = {
  value: number;
  unit: EnergyUnit;
};

type EventType = "SUSTAINABLE" | "UNSUSTAINABLE";

Example: Verify data in Javascript / Typescript (Node)​

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.

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();
  };

Update alerts​

You can update the alert, like setting the limit for triggering an alert using

  • updateEstimatedHourlyActiveEnergyLimitWarningAlertSetting
  • updateHourlyConsumptionLimitEstimationWarningAlertSetting
  • updateSustainableConsumptionAlertSetting