Webhooks einrichten
Verfügbar ab Plan Light.
Dieser Artikel behandelt Datenübertragungs-Webhooks: HTTP-POST-Zustellungen Ihrer Messwerte an einen externen Endpunkt, sobald neue Daten verfügbar sind.
Änderungen der Datenfreigabe meldet eine Verbindung über die Ereignisse weiter unten. Wie die Freigabe abläuft, beschreibt der Freigabefluss.
Ein Webhook ist eine HTTP-POST-Anfrage, die energiedaten.at automatisch an Ihre URL sendet, sobald neue Messwerte für einen zugewiesenen Zählpunkt eingehen. So erhalten externe Systeme die Daten sofort; ein eigener Abruf entfällt. Die Daten selbst sind T-1 (Werte des Vortages).
Verbindung erstellen

- Navigieren Sie zu Daten → Datenlieferungen → Datenlieferung hinzufügen.
- Wählen Sie den Typ Webhook.
- Geben Sie die Ziel-URL ein (muss HTTPS sein).
- Wählen Sie die gewünschte Sicherheitsmethode.
- Speichern Sie die Verbindung.
- Weisen Sie unter Zugeordnete Zählpunkte die gewünschten Zählpunkte zu.
Sicherheitsmethoden
| Methode | Einsatz |
|---|---|
| Keine | Für interne Systeme ohne externe Exposition |
| Basic Auth | Benutzername und Passwort, Base64-kodiert |
| Bearer Token | Statischer Token im Authorization: Bearer-Header; einfach zu implementieren, prüft aber nicht die Integrität des Payloads |
| HMAC-Signatur (empfohlen) | Kryptografische Signaturverifikation; prüft sowohl Herkunft als auch Payload-Integrität |
Payload-Format
Jede Anfrage enthält einen JSON-Body mit den Metadaten des Zählpunkts und den Messwerten:
{
"version": "1.0",
"event": "measurement.created",
"timestamp": "2025-03-16T12:00:00+01:00",
"smart_meter": {
"metering_point_number": "AT0010000000000000001000000000001",
"internal_reference": "building-7-floor-2",
"external_reference": "building-7-floor-2",
"energy_direction": "consumption",
"location": {
"name": "Headquarter",
"internal_reference": "HQ-01",
"external_reference": "HQ-01",
"address": "Musterstraße 1, 1010 Wien"
},
"customer": {
"name": "Muster GmbH",
"internal_reference": "C-1234",
"external_reference": "C-1234"
}
},
"records": [
{
"obis_code": "1-1:1.9.0 P.01",
"timestamp": "2025-03-15T23:00:00Z",
"timestamp_end": "2025-03-15T23:15:00Z",
"value": 0.285,
"data_quality": 1,
"unit": "kWh"
}
]
}
| Feld | Beschreibung |
|---|---|
event |
measurement.created für echte Zustellungen, test für Testzustellungen |
smart_meter.metering_point_number |
33-stellige österreichische Zählpunktnummer |
internal_reference |
Ihre eigene Referenz für Zählpunkt, Standort oder Kunde; gleicher Feldname wie in der REST-API |
external_reference |
Veraltet: gleicher Wert wie internal_reference. Stellen Sie auf internal_reference um |
smart_meter.location |
null, wenn kein Standort zugewiesen ist |
smart_meter.customer |
null, wenn kein Kunde zugewiesen ist oder die Kundenverwaltung nicht in Ihrem Plan enthalten ist |
records |
Array mit Viertelstundenwerten des Zählpunkts |
data_quality |
1 = Gemessen, 2 = Ersatzwert belastbar, 3 = Ersatzwert nicht belastbar |
Ereignisse zur Datenfreigabe
Eine Webhook-Verbindung meldet Ihnen auf Wunsch auch, wenn sich die Datenfreigabe eines Zählpunkts ändert. Ihr System muss dann den Zählpunktstatus nicht mehr über die REST-API abfragen.
| Ereignis | Wird gesendet, wenn |
|---|---|
meter.consent_pending_user |
der Netzbetreiber die Anfrage bestätigt hat und der Kunde im Netzbetreiberportal die Datenfreigabe noch bestätigen muss |
meter.consent_approved |
die Datenfreigabe erteilt worden ist und der Zählpunkt verbunden ist |
meter.consent_rejected |
die Anfrage abgelehnt worden ist, vom Netzbetreiber, vom Kunden im Portal oder weil der Kunde die Datenfreigabe nicht rechtzeitig bestätigt hat |
meter.consent_revoked |
die Datenfreigabe endet: Der Kunde hat widerrufen, der Netzbetreiber hat sie beendet oder Ihre Trennung ist bestätigt worden. Wird einmal gesendet, sobald das Ende feststeht |
Wechselt ein bereits verbundener Zählpunkt auf einen anderen Datenumfang, sendet die neue Anfrage meter.consent_pending_user und, wenn sie abgelehnt wird, meter.consent_rejected. Der Zählpunkt bleibt dabei verbunden, consent_process_state im Payload zeigt connected. Ist der Wechsel abgeschlossen, kommt kein meter.consent_approved. Anfragen nach historischen Daten lösen keine Ereignisse aus.
Eine Verbindung erhält die bei ihr ausgewählten Ereignisse für jeden Zählpunkt Ihres Teams, auch für Zählpunkte, die ihr nicht zugeordnet sind. Die Ereignisse wählen Sie beim Erstellen oder Bearbeiten der Verbindung unter Ereignisse zur Datenfreigabe aus; ohne Auswahl kommen nur Messdaten. Über die REST-API setzen Sie dafür das Feld subscribed_events.
{
"version": "1.0",
"event": "meter.consent_pending_user",
"event_id": "0b8f2a8e-4f4c-5d1e-9a3b-6c2d7e8f9a10",
"occurred_at": "2026-10-30T09:15:02+01:00",
"smart_meter": {
"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"metering_point_number": "AT0010000000000000001000000000001",
"label": "Wärmepumpe",
"internal_reference": "building-7-floor-2",
"consent_process_state": "waiting_for_user_confirmation",
"location_id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
"customer_id": "c3d4e5f6-a7b8-9012-cdef-123456789012"
},
"portal_url": "https://portal.example.at/zustimmung/1"
}
| Feld | Beschreibung |
|---|---|
event_id |
Bleibt bei jeder Wiederholung desselben Ereignisses gleich; damit erkennen Sie Duplikate |
occurred_at |
Zeitpunkt, zu dem sich die Datenfreigabe geändert hat; Ereignisse können in anderer Reihenfolge ankommen, sortieren Sie die Ereignisse eines Zählpunkts nach diesem Feld |
smart_meter.id |
ID des Zählpunkts, wie in der REST-API |
smart_meter.consent_process_state |
Status des Zählpunkts direkt nach der Änderung, etwa connected, ended oder not_connected |
location_id, customer_id |
IDs von Standort und Kunde aus der REST-API; customer_id ist null, wenn dem Standort kein Kunde zugewiesen ist |
portal_url |
Nur bei meter.consent_pending_user: Link zum Netzbetreiberportal, null, wenn der Netzbetreiber keinen mitgeschickt hat |
consent_end_date |
Nur bei meter.consent_revoked: der letzte Tag, den die Datenfreigabe abdeckt. Die Daten dieses Tages kommen noch an; der Zählpunkt bleibt bis dahin connected, ein weiteres Ereignis folgt nicht |
Ereignisse sind wie Messdaten signiert und erscheinen im Zustellprotokoll der Verbindung mit ihrem Ereignis und 0 Datensätzen. Ein fehlgeschlagenes Ereignis schaltet die Verbindung nie ab, und ein zugestelltes behebt kein Problem bei der Lieferung von Messdaten.
Verbindung testen
Klicken Sie auf Test senden, um eine Testzustellung mit einem Beispiel-Payload an Ihre URL zu senden. Der Statuscode der Antwort wird direkt angezeigt. Eine 2xx-Antwort gilt als erfolgreich.
Für Experten
HMAC-Signaturverifikation
Webhooks werden nach dem Verfahren Standard Webhooks signiert. Jede Standard-Webhooks-Bibliothek kann sie daher mit Ihrem Signaturschlüssel prüfen. Jede Anfrage enthält drei Header:
| Header | Inhalt |
|---|---|
webhook-id |
Die ID der Lieferung; bleibt bei jeder Wiederholung gleich, auch wenn Sie eine Lieferung erneut senden |
webhook-timestamp |
Unix-Zeitstempel dieses Versuchs, in Sekunden |
webhook-signature |
v1, gefolgt vom Base64-kodierten HMAC-SHA256 über {webhook-id}.{webhook-timestamp}.{body} |
Der HMAC-Schlüssel ist der Teil des Signaturschlüssels nach whsec_, Base64-dekodiert. Vergleichen Sie Signaturen timing-sicher und weisen Sie zu alte Zeitstempel ab, um Replays zu verhindern.
Um den Signaturschlüssel zu wechseln, klicken Sie daneben auf Schlüssel erneuern. Bis Sie auf Vorherigen Schlüssel entfernen klicken, trägt jede Anfrage eine Signatur für beide Schlüssel, durch ein Leerzeichen getrennt. Ihr Empfänger nimmt Anfragen also weiter an, während Sie ihn auf den neuen Schlüssel umstellen.
Retry-Verhalten
Antwortet Ihr Endpunkt mit 5xx oder 429 oder nicht innerhalb des Timeouts (höchstens 30 Sekunden), wird die Zustellung bis zu 3 Mal mit wachsender Pause wiederholt. Ein Retry-After-Header legt die Pause fest. Jede andere Antwort schlägt sofort fehl, auch Weiterleitungen, da sie nicht verfolgt werden.
Schlagen Zustellungen eine Stunde lang fehl, erhält Ihr Team einen Hinweis; die Verbindung bleibt aktiv. Nach 72 Stunden ohne erfolgreiche Zustellung, oder sofort bei einer Antwort 410 Gone, wird die Verbindung deaktiviert und Ihr Team erhält einen zweiten Hinweis. Die nächste erfolgreiche Zustellung beendet die Fehlerphase. Eine fehlgeschlagene Zustellung können Sie im Zustellprotokoll mit Erneut senden noch einmal schicken, siehe Zustellprotokolle & Fehler.