Webhooks

Introduction

Eliq offers a webhook solution which enables Eliq to send events to Utility API. To enable this, the utility would need to implement custom endpoints that Eliq can send webhook events to. The various types of webhook events can either be sent to the same endpoint, or to different endpoints. All webhook events are sent using POST.

Security

Endpoints must use HTTPS and can optionally use Basic HTTP Authentication or OAuth2.

Signature verification

Eliq signs all webhook events and sends the signature in the X-Eliq-Signature HTTP header. This allows your application to verify that Eliq generated the event. The X-Eliq-Signature HTTP header contains a timestamp and a signature. Timestamp is prefixed with t= and signature prefixed with the scheme used for signing the data. The current supported scheme is SHA256, and will be prefixed with sha256.

X-Eliq-Signature:
t=1591091590,
sha256=c39a4c26da13cba4258b698a3f849242af7d2e7b7559c50d0a94917355ff9532

Note: The signature is a hash-based message authentication code (HMAC) with SHA-256.

Verify signature

Eliq will generate a secret which is shared with the utility. That secret can be used to verify the signature. Below shows how the verification is done.

Step 1: Create signed payload

The signature includes the timestamp available in the X-Eliq-Signature HTTP header and the JSON string payload from the request body. To verify the signature, the timestamp and JSON string should be joined as follows:

{timestamp}.{json_payload}

Step 2: Compute expected signature

Compute an HMAC with the SHA256 hash function. Use your secret as the key and sign the payload generated in step 1.

Step 3: Compare expected signature

Compare signature received in X-Eliq-Signature HTTP header and your computed signature.

Retry policy

Eliq will retry to send events for a few times, with decreasing frequency, until the endpoint returns a 2xx status code within 10 seconds or until 24 hours have passed. A new timestamp and hash for the signature is generated for every retry. The Utility API must be able to handle duplicate events. Duplicate events can be detected by storing which event ids have been received.

Event payload

All events sent in the request body will have the same model structure. The event object will always include id, created_date (in UTC), type and object. The event.type defines how the event.object will look and how it should be parsed.

{
    "id": "a7b76b9f-ea64-4fd0-94db-624787fcb734",
    "created_date": "2020-01-01T21:23:00Z",
    "type": "{event_type}",
    "object": {
        ...
    }
}

Notification created

Notifications are defined as notifications that should be sent to the end user. In a white label solution, this is handled by sending push, SMS or email messages to the end user. In an API solution, Eliq does not have the ability to contact end users directly. However, the notifications that should have been sent out can be sent to the utility. The event.type for these events are notification_created.

The structure of the notification_created object model always includes a location_id, location_ext_ref, type and object. The notification_created.type defines how the notification_created.object will look and how it should be parsed.

{
    "id": "a7b76b9f-ea64-4fd0-94db-624787fcb734",
    "created_date": "2020-01-01T21:23:00Z",
    "type": "notification_created",
    "object": {
        "location_id": 1234,
        "location_ext_ref": "{location_ext_ref}",
        "type": "{notification_type}",
        "object": {
            ...
        }
    }
}

‍

Event types

The following event types are supported.

Budget notification

Two of the possible notification types are budget_weekly and budget_monthly. This is sent when a weekly or monthly budget is either completed and under budget, or if budget exceeds the limit. A notification can also be sent if the forecast indicates that the user will exceed the limit.

The budget object will be the same as in API V3 and will look as follows:

{
    "id": "a7b76b9f-ea64-4fd0-94db-624787fcb734",
    "created_date": "2020-01-01T21:23:00Z",
    "type": "notification_created",
    "object": {
        "enabled": true,
        "type": "budget_weekly",
        "fuel": "elec",
        "resolution": "week",
        "unit": "cost",
        "limit": 15.0,
        "suggested_limit": 0.38,
        "status": {
            "code": "ok",
            "value": 0.38,
            "forecast": 0.38,
            "period_start": "2025-06-23T00:00:00",
            "period_end": "2025-06-30T00:00:00",
            "data_until": "2025-06-25T00:00:00",
            "result": "currently_below"
        }
    }
}

Anomaly notification

There are two possible notification types: daily_anomaly and monthly_anomaly. The notifications are sent if we detect that a location’s yesterday’s consumption was lower/higher than what we expect it to be or if we detect that a location’s consumption for the current month is unusually high.

The anomaly object schema looks like the following:

{
    "id": "a7b76b9f-ea64-4fd0-94db-624787fcb734",
    "created_date": "2020-01-01T21:23:00Z",
    "type": "notification_created",
    "object": {
        "location_id": 1234,
        "location_ext_ref": "{location_ext_ref}",
        "type": "daily_anomaly",
        "object": {
            "type": "daily_anomaly",
            "fuel": "elec",
            "status": {
                "data_until": "2020-04-08T00:00:00.000",
                "result": "high"
            }
        }
    }
}

Market Price notifications

The two possible notification types for this feature are notifications_market_price_next_day_hour_price_alert and notifications_market_price_next_day_avg_price_alert and are generated and sent at 17:00 Stockholm time if there are any price alerts for the next day to send out.

The market price objects will be the same as in Insights API and will look as follows:

{
  "client_id": 123456789,
  "location_id": 1234,
  "location_ext_ref": "{location_ext_ref}",
  "type": "market_price_next_day_avg_price",
  "object": {
    "level": "low",
    "abs_percentage_difference": 53,
    "avg_price_kwh": "0.3517083333333333333333333333",
    "highest_price_kwh": {
      "period_start": "2022-11-06T17:00:00",
      "price_kwh": "0.544240"
    },
    "lowest_price_kwh": {
      "period_start": "2022-11-06T23:00:00",
      "price_kwh": "0.215760"
    },
    "type": "market_price_next_day_avg_price",
    "date": "2022-11-06"
  }
}

{
  "client_id": 123456789,
  "location_id": 1234,
  "location_ext_ref": "{location_ext_ref}",
  "type": "market_price_next_day_high_peak",
  "object": {
    "highest_price_period_start": "2022-11-04T19:00:00",
    "highest_price_kwh": "2.323090",
    "type": "market_price_next_day_high_peak",
    "date": "2022-11-04"
  }
}

Monthly Report notifications

Monthly Insights Notifications provide a concise summary of last month's energy usage. The only notification type for this feature is monthly_insight. They are generated and sent once the previous month’s consumption is available for a given location.

‍

The notification objects looks like the following:

{
    "id": "882656c3-f4bd-4b75-a954-b45c68185fba",
    "created_date": "2024-02-01T03:23:00Z",
    "type": "notification_created",
    "object": {
        "location_id": 123,
        "location_ext_ref": "EXT_REF",
        "type": "monthly_insight",
        "message": {
          "language":{
            "sv-SE": {
              "header": "Your consumption in January",
              "content": "You consumed 3456 kWh in January which 
              is about the same as the same month last year.
              The consumption decreased 45 kWh compared to 
              December. Check out all your insights in the app."
            }
          }
        },
        "object": {
            "type": "monthly_insight",
            "fuel": "elec",
            "period_start": "2024-01-01T00:00:00.000",
            "period_end": "2024-02-01T00:00:00.000"
        }
    }
}

Connection status updates

The two possible notification types for this feature are connection_action_required and connection_first_data_recieved and are sent when status changes for the connection

• Only need to notify user if status changes through background syncs
  • ConnectionMaintanance.RunEnergyDataSyncForConnectionEntityMetersAsync
    • [connection_first_data_recieved] If there are any data syncs (1 per connection entity) awaiting their first data sync, status should be awaiting first data sync. → Once all entities has LastSucceededAtTimestamp != null, we should notify user.
  • ConnectionMaintanance.RefreshConnectionsAsync
    • Method will accept “allow_user_notifications” to know if we should trigger notification for status changes in this method (i.e avoid is method is called from user)
    • connectionProvider.GetConnectionAsync returns “not found”
      • → Deleted (connection.DeleteConnectionAsync)
    • Status change
      • [connection_action_required] AwaitingConfirmation → Disconnected

connection_action_required

{
  "client_id": 123456789,
  "location_id": 1234,
  "location_ext_ref": "{location_ext_ref}",
  "type": "connection_action_required",
  "object": {
    "connection_id": "3AA8FC59-607E-EE11-8925-000D3A241A52",
    "type": "connection_action_required"
  }
}

connection_first_data_recieved

{
  "client_id": 123456789,
  "location_id": 1234,
  "location_ext_ref": "{location_ext_ref}",
  "type": "connection_first_data_recieved",
  "object": {
    "connection_id": "3AA8FC59-607E-EE11-8925-000D3A241A52",
    "type": "connection_first_data_recieved"
  }
}