Webhooks einrichten

Verfügbar ab Plan Starter.

Ein Webhook ist eine HTTP-POST-Anfrage, die energiedaten.at automatisch an Ihre URL sendet, sobald neue Messwerte für einen zugewiesenen Zähler eingehen. So erhalten externe Systeme Daten sofort bei Verfügbarkeit, ohne polling. 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 Ausgabe → Verbindungen → Neue Verbindung.
  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 Routen die gewünschten Zähler 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ählers und den Messwerten:

{
  "version": "1.0",
  "event": "measurement.created",
  "timestamp": "2025-03-16T12:00:00+01:00",
  "smart_meter": {
    "metering_point_number": "AT0010000000000000001000000000001",
    "external_reference": "building-7-floor-2",
    "energy_direction": "consumption",
    "location": {
      "name": "Headquarter",
      "external_reference": "HQ-01",
      "address": "Musterstraße 1, 1010 Wien"
    },
    "customer": {
      "name": "Muster GmbH",
      "external_reference": "C-1234"
    }
  },
  "records": [
    {
      "obis_code": "1-1:1.8.0",
      "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
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ählers
data_quality 1 = Gemessen, 2 = Geschätzt, 3 = Unzuverlässig

Verbindung testen

Klicken Sie auf Testen, 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.

HMAC-Signaturverifikation

Bei aktivierter HMAC-Signatur fügt energiedaten.at den Header Signature zur Anfrage hinzu. Der Wert ist ein HMAC-SHA256-Hex-Digest des JSON-Request-Bodys, signiert mit Ihrem konfigurierten Signing Secret.

Zur Verifikation berechnen Sie hash_hmac('sha256', $requestBody, $secret) und vergleichen das Ergebnis mit dem Header-Wert mittels eines timing-sicheren Vergleichs.

Retry-Verhalten

Bei einem Fehler (kein 2xx oder Timeout) wird die Zustellung mit exponentiellem Backoff bis zu 2 Mal wiederholt. Nach 5 aufeinanderfolgenden fehlgeschlagenen Zustellungen wird die Verbindung automatisch deaktiviert. Einzelne fehlgeschlagene Zustellungen können manuell unter Zustellprotokolle & Fehler erneut gesendet werden.