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.
V2 API Usage (Recommended)
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:
- nodered_flow.json: generic incoming webhook flow.
- nodered_mqtt_bridge_flow.json: MQTT-to-EnergyID bridge flow with per-device claiming, buffering, and upload policy handling.
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)
| 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)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| 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 logRelease 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 logSecurity 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.
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 logA 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.