Developers
Incoming Webhooks
Web API

      • Incoming Webhooks

        Incoming Webhooks are a simple way to send meter readings from apps and devices to EnergyID.
        Creating an Incoming Webhook gives you a unique URL to which you send a JSON payload containing the meter readings.

        To get started, follow these three easy steps:

        1. Go to the incoming webhook page and click activate.
        2. Pick the record you would like to send readings to, and provide a name for your application or device.
        3. Copy the generated Webhook URL.

        We'll show how you can generate webhooks programmatically later.

        Use your Incoming Webhook URL to post meter readings

        Just make an HTTP POST request like this: 

        
POST https://hooks.energyid.eu/services/WebhookIn/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxxxxxx
Content-type: application/json
{
    "remoteId": "my-solar-inverter",
    "remoteName": "My Solar Panels",
    "metric": "solarPhotovoltaicProduction",
    "metricKind": "total",
    "unit": "kWh",    
    "interval": "PT15M",  
    "data": [
        ["2022-10-05T08:00+0200", 0.004],
        ["2022-10-05T08:15+0200", 0.012],
        ["2022-10-05T08:30+0200", 0.037],
        ["2022-10-05T08:45+0200", 0.060],
        ["2022-10-05T09:00+0200", 0.114],
        ["2022-10-05T09:15+0200", 0.197],
        ["2022-10-05T09:30+0200", 0.248],
        ["2022-10-05T09:45+0200", 0.300]
    ]
}

        The URL to which you send the HTTP POST request must be the same URL you generated earlier.

        As shown in the example above the POST body needs to be a JSON object containing a handful of properties:

        Property Type Required Description
        remoteId string Required The unique identifier of the data stream in your local environment.
        This property is used by the webhook to lookup the corresponding meter in your EnergyID record. If no matching meter is found, the webhook will automatically create one.
        remoteName string Required The human readable name of the data stream in your local environment. This is used as a display name for the corresponding EnergyID meter.
        metric string Required

        The metric that is being measured. Check your webhook policy to know what metrics are supported.

        Energy
        electricityImport, electricityExport, solarPhotovoltaicProduction, naturalGasImport, districtHeatingImport, districtCoolingImport, pelletsStockDraw, firewoodStockDraw, woodBriquettesStockDraw, fuelOilStockDraw, fuelOilStockBuild, fuelOilStockLevel, propaneStockDraw, butaneStockDraw, solarThermalProduction, windPowerProduction, cogenerationPowerProduction, electricVehicleCharging, finalElectricityConsumption, finalHeatConsumption, finalCoolingConsumption
        Water
        drinkingWaterImport, rainwaterStockDraw, groundwaterImport
        Waste
        glassWaste, paperAndCardboardWaste, pmdWaste, softPlasticsWaste, organicWaste, residualWaste, electronicWaste
        Comfort
        indoorTemperature, outdoorTemperature, relativeIndoorHumidity, relativeOutdoorHumidity
        Mobility
        distanceTravelledByCar, distanceTravelledByBike, distanceTravelledByMotor, distanceTravelledByScooter, distanceTravelledByPlane
        metricKind string Required

        One of the supported metric kinds, describing how we should interpret the values:

        cumulative - A value accumulated over a time interval. The value can only reset when the counter reaches its maximum possible value.
        total - The change in a value during a time interval. The timestamp indicates the start of the time interval.
        delta - The change in a value during a time interval. The timestamp indicates the end of the time interval.
        gauge - An instantaneous measurement of a value. An example of a gauge metric is the current temperature.
        quantity - A discrete quantity at a specific point in time, such as the number of trash bags or the actual weight of the collected waste. The value is not tied to a time interval but reflects a specific amount at that moment.
        unit string Required The unit in which the values are expressed.
        Can be kWh, Wh, l, m³, kg, km, °C, %, count.
        interval string Optional The ISO 8601 time interval between data points. Check your webhook policy to know the shortest time interval allowed by the webhook.
        Can be P1D, PT1H, PT15M, PT5M. Leave empty for manual meter readings.
        multiplier double Optional A multiplier (or conversion factor) to convert measured values to the reported value.
        Default is 1.
        meterNumber string Optional The meter number associated with the data stream.
        ean string Optional The EAN number associated with the data stream.
        register string Optional The register or time frame associated the with the data stream.
        Can be high, low, lowExclusive, peak.
        data array Required An array of data points. A data point exists of a timestamp and a numeric value in that specific order.
        Please note that the number of data points per request cannot exceed 1000.
        All timestamps should be in ISO 8601 format containing timezone information. These timestamps look something like 2019-08-05T15:05:15+01:00.

        Get your webhook policy

        A webhook is governed by a policy that determines what metrics and intervals are allowed in your Basic or Premium plan.

        Just make an HTTP GET request to get the webhook policy: 

        
GET https://hooks.energyid.eu/services/WebhookIn/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxxxxxx

        The response will look this: 

        
{
    "displayName": "Webhook policy",
    "description": "This policy enables your app to restrict the metrics it sends to this webhook.",
    "allowedMetrics": [
        "electricityImport",
        "electricityExport",
        "naturalGasImport",
        "solarPhotovoltaicProduction",
        ...
    ],
    "allowedInterval": "P1D"
}

        The policy defines the allowed metrics and the allowed interval.

        • allowedMetrics - The list of metrics allowed by the webhook.
        • allowedInterval - The shortest time interval between data points allowed by the webhook.

        If your current webhook policy isn't a good fit, you can upgrade your subscription.

        Error Handling

        Though in most cases you'll receive a HTTP 200 response indicating that your metering data was posted successfully, it's best to prepare for scenarios where attempts to send a payload will fail. Incoming webhooks may throw errors when receiving malformed requests, when the webhook URL is no longer valid, or when something exceptional prevents us from storing your metering data.

        HTTP error Short description
        404   Not found The webhook URL does not exsist or is no longer available
        400   Bad Request The payload sent in your request cannot be understood.
        403   Forbidden The webhook associated with your request has been disabled.

        Rate Limits

        Incoming Webhooks allow 30 requests per 15 minutes. If you go over these limits, we will start returning a HTTP 429 Too Many Requests error, and a Retry-After HTTP header containing the number of seconds until you can retry.

        To avoid reaching this limit, consider running your proces every 15 minutes or even less frequently.

        Generating Incoming Webhook URLs programmatically

        In the guide above we showed you how to quickly generate a webhook URL manually, but when you have an existing App, you'll need a way to generate those URLs on the fly. Fortunately, Incoming Webhooks can be easily generated using OAuth.

        1. Get user consent

        Before you can begin to create webhooks automatically, you must register your App. Once you have obtained your Client ID and Client Secret you can initiate the OAuth flow. Make sure you include the incoming-webhook permission in the scope list. When you do, users will see an additional permission on the Authorize screen that lets them pick the record where Incoming Webhooks will post to, as shown below.

        2. Grab Incoming Webhook URL from the OAuth response

        Once a user gives consent to your app, and your app has completed the OAuth verification code exchange, you'll receive a JSON response like this:

        
{
    "access_token": "XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
    "scope": "incoming_webhook",
    "incoming_webhook": {
        "record_name": "My Home",
        "record_number": "EA-XXXXXXXX",
        "url": "https://hooks.energyid.eu/services/WebhookDemo/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/xxxxxxxxxxxx"
    }
}

        You can see that this OAuth response contains an incoming_webhook object, and right there in the url property is your brand new Incoming Webhook URL. You can now go ahead and use this URL to post readings, as demonstrated above.

        Here's a full explanation of all the properties in this incoming_webhook object:

        Property Type Description
        record_name string The name of the record that the user selected as a destination for readings.
        record_number string The unique record number of the same record.
        url string The Incoming Webhook URL

        Upgrade your legacy webhook

        The Incoming Webhook integration has been updated to better support basic time series operations, such as downsampling and interpolation. The new JSON payload has additional properties that weren't required in the legacy version.

        Make sure you update your JSON payload.

        • Remove the property meterId, as your webhook can no longer send data to a meter that has been created manually. We aim for full seperation of automated and manual data flows.
        • Add context information such as remoteId, remoteName, metric, metricKind, and unit.
        • Set the interval property to P1D in case you send daily values.
        • Send the new JSON payload to your webhook. The webhook will automatically create a new meter and link it to the provided remote id.
        • Do not delete the old meter in your EnergyID Record unless you are able to resend all historical data using the updated JSON payload.

      • Web API

        EnergyID Web API allows Apps to integrate with EnergyID and go beyond the integrations we provide out of the box.

        You can get a detailed description of all the available endpoints in our API reference documentation.
        If your App only needs to post meter readings to an EnergyID record, use our Incoming Webhooks.

        API Reference Documentation

        Authentication

        EnergyID Web API uses the OAuth 2.0 protocol for authentication and authorization. EnergyID supports common OAuth 2.0 scenarios such as those for web server, installed, and client-side applications.

        All applications follow a basic pattern when accessing the EnergyID Web API using OAuth 2.0. At a high level, you follow four steps:

        1. Obtain OAuth 2.0 credentials.

        Register your app to obtain OAuth 2.0 credentials such as a client ID and client secret.

        2. Obtain an access token from the EnergyID Authorization Server.

        Before your application can access private data using EnergyID Web API, it must obtain an access token. A variable parameter called scope controls the set of resources and operations that an access token permits. During the access-token request, your application sends one or more values in the scope parameter.

        To begin, request an authorization code for your app. Call GET https://identity.energyid.eu/connect/authorize and fill the following parameters:

        • client_id - issued when you created your app
        • scope - permissions to request (see below)
        • response_type - should be set to code
        • redirect_uri - the callback URL that will catch the authorization code
        • state - unique string to be passed back upon completion (optional)
        • ui_locales - gives a hint about the desired display language of the login and user consent screen, for example en-GB, nl-BE (optional)

        Our interactive OAuth flow requires an authentication step where the user logs in with their EnergyID account. After logging in, the user is asked whether they are willing to grant the permissions that your application is requesting. This process is called user consent. If the user grants the permission, the EnergyID Authorization Server sends your application an authorization code that your application can use to obtain an access token. If the user does not grant the permission, the server returns an error.

        The authorization code is passed to your redirect URL along with the requested scopes. You can now exchange this authorization code for an access token by calling POST https://identity.energyid.eu/connect/token.

        • client_id - issued when you created your app
        • client_secret - issued when you created your app
        • grant_type - should be set to authorization_code
        • code - the authorization code obtained by the previous call
        • redirect_uri - the URL to be redirected to after authorization (this must be the same uri as the one from the previous call)

        3. Send the access token to an API endpoint.

        Whenever making any API request to EnergyID, you will need to include your access token in the request headers. Authorization: bearer {AccessToken}.

        4. Refresh the access token, if necessary.

        Access tokens have limited lifetimes. If your application needs access to EnergyID Web API beyond the lifetime of a single access token, it can obtain a refresh token. A refresh token allows your application to obtain new access tokens. Call POST https://identity.energyid.eu/connect/token and pass the following body:

        • client_id - issued when you created your app
        • client_secret - issued when you created your app
        • grant_type - should be set to refresh_token
        • refresh_token - the refresh token obtained along with the access token

        Note that a refresh token is only provided when you include the offline_access scope in the authorize call.

        Permission scopes

        OAuth scopes let you specify exactly how your app needs to access a member's account. As an app developer, you specify your desired scopes in the initial OAuth authorization request. When a member is responding to your OAuth request, the requested scopes will be displayed to them when they are asked to approve your request.

        EnergyID uses scopes that refer to the object they grant access to, followed by the class of actions on that object they allow (e.g. records:write).

        The list of objects includes records, groups and profile. The supported actions are read and write.

        Scope Short description
        profile:read Read only access to the member's profile
        profile:write Full access to the member's profile
        records:read Read only access to the member's records
        records:write Full access to the member's records
        groups:read Read only access to the member's groups
        groups:write Full access to the member's groups

        Object models

        All Web API endpoints return data in JSON format.

        Some endpoints return simplified versions of the resource objects. In general endpoints that return multiple objects will return a list of simplified objects. Simplified objects always contain an id which can be used to get full details of the object.

        Object Short description
        Record In general a record represents a building with its own address. Records have a collection of meters.
        Meter Meter objects are a representation of actual, physical flows that can be measured. The meter's metric describes what flow is measured and where in the flow it is measured. To get a better overview, the meters are devided into themes.
        Reading A reading is one data point in the meter's flow. It consists of a timestamp, value and validation code.
        Group A group is a collection of records.

        Datasets

        For each record we calculate performance metrics for energy, water, waste and mobility.

        You can break down and filter results by one of the supported dimensions. Use one dimension for filtering and another for grouping.

        Name Description
        Energy
        energyEmissions
        Energy Emissions (kg)
        Measures energy CO2 emissions.
        Measurement: Weighted Delivered Energy - Weighted Exported Energy
        Weighting: CO2 emission factors (from kWh to kg CO2-equivalent)
        Dimensions:
        Name Type Filter Grouping Supported values
        carrier string Yes Yes biomass, butane, districtCooling, districtHeating, electricity, fuelOil, liquidGas, naturalGas, solarThermal
        type string Yes Yes electric, nonElectric
        energyProduction
        Energy Production (kWh)
        Measures on-site energy production in kWh.
        Measurement: Total Energy Production
        Dimensions:
        Name Type Filter Grouping Supported values
        carrier string Yes Yes cogenElectricity, solarPhotovoltaic, solarThermal, wind
        type string Yes Yes electric, nonElectric
        meter guid No Yes The id of each energy production meter.
        energyUse
        Energy Use (kWh)
        Measures energy consumption in kWh.
        Measurement: Total Delivered Energy - Total Exported Energy
        Dimensions:
        Name Type Filter Grouping Supported values
        carrier string Yes Yes biomass, butane, districtCooling, districtHeating, electricity, fuelOil, liquidGas, naturalGas, solarThermal
        type string Yes Yes electric, nonElectric
        energyGridOfftake
        Energy Grid Offtake (kWh)
        Measures energy taken from the grid in kWh.
        Dimensions:
        Name Type Filter Grouping Supported values
        carrier string Yes Yes districtCooling, districtHeating, electricity, naturalGas,
        type string Yes Yes electric, nonElectric
        energyGridInjection
        Energy Grid Injection (kWh)
        Measures energy injected in the grid in kWh.
        Dimensions:
        Name Type Filter Grouping Supported values
        carrier string Yes Yes electricity
        type string Yes Yes electric
        selfConsumption
        Self Consumption
        Measures the on-site production that is consumed locally.
        Measurement: (Total Production - Total Grid Injection)
        Dimensions:
        Name Type Filter Grouping Supported values
        type string Yes No electric, nonElectric
        selfConsumptionRatio
        Self Consumption Ratio (%)
        Measures the percentage of the on-site production that is consumed locally.
        Measurement: (Total Production - Total Grid Injection) / Total Production
        Dimensions:
        Name Type Filter Grouping Supported values
        type string Yes No electric, nonElectric
        selfSufficiency
        Self Sufficiency
        Measures the consumed energy that is produced locally.
        Measurement: (Total Energy Use - Total Grid Offtake)
        Dimensions:
        Name Type Filter Grouping Supported values
        type string Yes No electric, nonElectric
        selfSufficiencyRatio
        Self Sufficiency Ratio (%)
        Measures the percentage of the consumed energy that is produced locally.
        Measurement: (Total Energy Use - Total Grid Offtake) / Total Energy Use
        Dimensions:
        Name Type Filter Grouping Supported values
        type string Yes No electric, nonElectric
        Water
        waterUse
        Water Use (l)
        Measures water consumption in liter.
        Measurement: Total Water Use
        Dimensions:
        Name Type Filter Grouping Supported values
        type string Yes Yes drinkingWater, groundwater, rainwater
        meter guid No Yes The id of each water consumption meter.
        Waste
        solidWaste
        Solid Waste (kg)
        Determines solid waste consumption in kg.
        Measurement: Total Solid Waste
        Dimensions:
        Name Type Filter Grouping Supported values
        fraction string Yes Yes electronicWaste, glass, organicWaste, paperAndCardboard, pmd, residualWaste, softPlastics
        type string Yes Yes biodegradable, recyclable, residual, special
        meter guid No Yes The id of each solid waste meter.
        solidWasteRecovery
        Solid Waste Recovery (%)
        Measures the percentage of total solid waste that is recovered by composting, by conversion to biogas or by recycling.
        Measurement: Total Solid Waste Recovered / Total Solid Waste
        Mobility
        distanceTravelled
        Distance Travelled (km)
        Determines the distance travelled in km.
        Measurement: Total Distance Travelled
        Dimensions:
        Name Type Filter Grouping Supported values
        vehicleType string Yes Yes bike, car, motor, scooter
        meter guid No Yes The id of each mobility meter.

        Benchmark

        The following benchmark metrics are available for households and schools.

        Benchmarks are only available if a minimum number of users are contributing their results to the calculation. Additionally, benchmarks are only calculated for calendar years and months.

        Name Description
        energyEmissionsPerGsm
        Energy Emissions per m2 (kg)
        Benchmark the daily energy CO2 emissions per gross square meter.
        Measurement: Average Daily Energy CO2 Emissions / Total Gross Area
        Value-based filters: Energy Type
        energyEmissionsPerOccupant
        Energy Emissions per Occupant (kg)
        Benchmark the daily energy CO2 emissions per occupant.
        Measurement: Average Daily Energy CO2 Emissions / Total People
        Value-based filters: Energy Type
        energyUsePerGsm
        Energy Use per m2 (kWh)
        Benchmark the daily energy consumption per gross square meter.
        Measurement: Average Daily Energy Use / Total Gross Area
        Value-based filters: Energy Type
        energyUsePerOccupant
        Energy Use per Occupant (kWh)
        Benchmark the daily energy consumption per occupant.
        Measurement: Average Daily Energy Use / Total People
        Value-based filters: Energy Type
        waterUsePerOccupant
        Water Use per Occupant (l)
        Benchmark the daily water consumption per occupant.
        Measurement: Average Daily Water Use / Total People
        Value-based filters: Water Type
        For the moment only drinkingWater is supported.

        Timezones

        Some requests allow for specifying timestamps or generate timestamps with time zone information. These requests explicitly provide an ISO 8601 timestamp with timezone information and look something like 2018-08-05T15:05:06+01:00.

        Register your application

        If you want to use EnergyID Web API or distribute your Incoming Webhook as an App, you should first register your application. You can do this by sending us an email with the following information:

        • Application name
        • An icon for the application
        • URL to the application’s home page
        • A short description of the application
        • A link to the application’s privacy policy
        • A list of redirect URLs
        • A list of required scopes