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 in Echtzeit, ohne polling.

Verbindung erstellen

  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 Authentifizierungsmethode.
  5. Speichern Sie die Verbindung.
  6. Weisen Sie unter Routen die gewünschten Zähler zu.

Authentifizierungsmethoden

| Methode | Einsatz | |---|---| | HMAC-Signatur | Empfohlen — kryptografische Verifikation des Absenders | | Bearer Token | Einfacher API-Token im Authorization-Header | | Basic Auth | Benutzername und Passwort, Base64-kodiert | | Keine | Für interne Systeme ohne externe Exposition |

Payload-Format

Jede Anfrage enthält einen JSON-Body mit den Messwerten des Zählers:

{
  "meter_id": "AT0010000000000000001000000000001",
  "timestamp": "2025-03-16T08:15:00+01:00",
  "value_kwh": 0.285,
  "unit": "kWh",
  "quality": "measured"
}

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 X-Signature-256 zur Anfrage hinzu. Der Wert ist ein HMAC-SHA256-Hash des rohen Request-Bodys, signiert mit Ihrem konfigurierten Signing Secret.

Verifikation in PHP:

$payload = file_get_contents('php://input');
$secret  = 'Ihr_Signing_Secret';
$header  = $_SERVER['HTTP_X_SIGNATURE_256'] ?? '';

$expected = 'sha256=' . hash_hmac('sha256', $payload, $secret);

if (!hash_equals($expected, $header)) {
    http_response_code(401);
    exit;
}

Retry-Verhalten

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