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

Webhook-Konfiguration: Name, Ziel-URL, Sicherheitsmethode per HMAC-Signatur, Datenformat und JSON-Vorschau des Payloads.
Webhook-Konfiguration: Name, Ziel-URL, Sicherheitsmethode per HMAC-Signatur, Datenformat und JSON-Vorschau des Payloads.
  1. Navigieren Sie zu Daten → Datenlieferungen → Datenlieferung hinzufügen.
  2. Wählen Sie den Typ Webhook.
  3. Geben Sie die Ziel-URL ein (muss HTTPS sein).
  4. Wählen Sie die gewünschte Sicherheitsmethode.
  5. Speichern Sie die Verbindung.
  6. 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:

JSON
{
    "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.

JSON
{
    "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.