Skip to main content

energyid-webhooks

Python package for interfacing with EnergyID Webhooks (supports both V1 and V2 APIs)

Installation

pip install energyid-webhooks

Features

  • V2 API support with device provisioning and claiming
  • Authentication with automatic token renewal
  • Smart sensor bundling for efficient data transmission
  • Async support
  • Full type hints

Type Checking

This package is fully type-hinted and checked with strict mypy settings.

The V2 API includes device provisioning, authentication, and smart bundling:

import asyncio
from energyid_webhooks import WebhookClient

# Create the client
client = WebhookClient(
    provisioning_key="your_provisioning_key",
    provisioning_secret="your_provisioning_secret",
    device_id="unique_device_id",
    device_name="My Device",
    reauth_interval=24  # Hours between token refresh
)

async def main():
    # Authenticate with EnergyID
    is_claimed = await client.authenticate()

    if not is_claimed:
        # Device needs to be claimed
        claim_info = client.get_claim_info()
        print(f"Claim your device at {claim_info['claim_url']} with code {claim_info['claim_code']}")
        # Wait for claiming...
        return

    # Add and update sensors
    await client.update_sensor("el", 1250.5)  # Electricity consumption
    await client.update_sensor("pv", 3560.2)  # Solar production

    # Synchronize with EnergyID
    await client.synchronize_sensors()

    # Or enable automatic synchronization
    client.start_auto_sync(interval_seconds=300)  # Every 5 minutes

    # Don't forget to close when done
    await client.close()

asyncio.run(main())

Refused credentials

authenticate() raises EnergyIDAuthenticationError when EnergyID refuses the provisioning key and secret (HTTP 401) or the linked record is closed (HTTP 403). The client also signs in again by itself (before its token expires, and after a directive request is rejected), so send_data(), synchronize_sensors(), get_directives() and get_directive_data() can raise it too. Ask the user for new credentials; retrying does not help. start_auto_sync() only logs errors, so call synchronize_sensors() yourself if you need to react to this one. The error subclasses aiohttp.ClientResponseError, so existing handlers keep working.

Directives

A device whose record was granted directive access can read the directive schedules:

import datetime as dt

directives = await client.get_directives()
for directive in directives:
    schedule = await client.get_directive_data(directive.id)
    state = schedule.state_at(dt.datetime.now(dt.UTC))
    print(directive.title, state.current, state.next_change, state.next_signal)

Each point in a schedule starts a slot that lasts one interval. Day and week slots (P1D, P7D) follow the local calendar: on the day the clocks change, a slot still runs until the next point when that point starts at the same local time. When the interval has no fixed length (P1M, P1Y), a slot lasts until the next point, and the last one never ends. state_at() returns the active point (None outside every slot), the next time the signal value changes, and the point that starts then (None when the change is to no signal: a gap or the end of the last slot). signal_at() returns only the active point. Both need a timezone-aware moment.

V1 API Usage (Legacy)

The original API is still available for backward compatibility:

from energyid_webhooks import WebhookClientV1, WebhookPayload

url = "https://app.energyid.eu/integrations/WebhookIn/..."

client = WebhookClientV1(url)

# Post some data to the webhook
data = {
    'remoteId': 'my-solar-inverter',
    'remoteName': 'My Solar Panels',
    'metric': 'solarPhotovoltaicProduction',
    'metricKind': 'total',
    'unit': 'kWh',
    'interval': 'P1D',
    'data': [['2022-10-05T08:00+0200', 0.004]]
}

client.post(data)

V1 Async Usage (Legacy)

import asyncio
from energyid_webhooks import WebhookClientAsyncV1

url = "https://app.energyid.eu/integrations/WebhookIn/..."

client = WebhookClientAsyncV1(url)

async def main():
    data = {
        'remoteId': 'my-solar-inverter',
        'remoteName': 'My Solar Panels',
        'metric': 'solarPhotovoltaicProduction',
        'metricKind': 'total',
        'unit': 'kWh',
        'interval': 'P1D',
        'data': [['2022-10-05T08:00+0200', 0.004]]
    }

    await client.post(data)

asyncio.run(main())

Demos

See the demos folder for cURL, Python notebook, Node-RED, and Apache NiFi examples.

Node-RED examples include:

Development

Setup

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

Metadata

Release files for energyid-webhooks 0.0.17

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for energyid-webhooks 0.0.17
File Size Uploaded Provenance Actions
energyid_webhooks-0.0.17.tar.gz 130.9 kB With provenance Details for energyid_webhooks-0.0.17.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for energyid-webhooks 0.0.17
File Interpreter ABI Platform Actions
energyid_webhooks-0.0.17-py3-none-any.whl Python 3 none any Details for energyid_webhooks-0.0.17-py3-none-any.whl

Total release size: 148.0 kB

Release files / energyid_webhooks-0.0.17.tar.gz

Download URL energyid_webhooks-0.0.17.tar.gz
Size 130.9 kB
Tags Source
SHA-256 checksum
How to use checksums
58c51c492503a760892fb835ec85b501a173804a9908dafa0821b20e64adcd41
BLAKE2b-256 checksum
How to use checksums
94d6c7ea2f5acf0dbd6c2742f21ce1ae86011153adaba301a903c416d65ec5f8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Release files / energyid_webhooks-0.0.17-py3-none-any.whl

Download URL energyid_webhooks-0.0.17-py3-none-any.whl
Size 17.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
80d605aa4ea03922d8af2978525528793d1c4b1f7a08f1ed16db74ccf215692a
BLAKE2b-256 checksum
How to use checksums
9d59153901a9424e8aa74a65bddafc6bda00019833545733a32aa5b23209b0f5
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

Security for energyid-webhooks 0.0.17

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for energyid_webhooks-0.0.17.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 13, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page