Set Up Webhooks

Available from the Light plan.

This article covers data-delivery webhooks: HTTP POST deliveries of your measurement data to an external endpoint as soon as new data becomes available.

A connection reports consent changes through the consent events described below. How consent works is described in Consent flow.

A webhook is an HTTP POST request that energiedaten.at automatically sends to your URL as soon as new readings arrive for an assigned metering point. This gives external systems the data immediately; no polling required. The data itself is T-1 (values from the previous day).

Create a Connection

Webhook configuration: name, target URL, security method via HMAC signature, data format, and JSON preview of the payload.
Webhook configuration: name, target URL, security method via HMAC signature, data format, and JSON preview of the payload.
  1. Go to Data → Data deliveries → Add data delivery.
  2. Select the type Webhook.
  3. Enter the target URL (must be HTTPS).
  4. Choose the desired security method.
  5. Save the connection.
  6. Assign the meters you want under Assigned metering points.

Security Methods

Method Use case
None For internal systems without external exposure
Basic Auth Username and password, Base64-encoded
Bearer Token Static token sent in the Authorization: Bearer header; simple to implement, but does not verify payload integrity
HMAC Signature (recommended) Cryptographic signature verification; verifies both origin and payload integrity

Payload Format

Each request contains a JSON body with the meter metadata and measurement records:

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"
        }
    ]
}
Field Description
event measurement.created for real deliveries, test for test deliveries
smart_meter.metering_point_number 33-character Austrian metering point ID (Zählpunkt)
internal_reference Your own reference for the meter, location or customer; same field name as in the REST API
external_reference Deprecated: same value as internal_reference. Switch to internal_reference
smart_meter.location null if no location is assigned
smart_meter.customer null if no customer is assigned or the Customer Management feature is not included in your plan
records Array of quarter-hour readings for the meter
data_quality 1 = Measured, 2 = Reliable substitute value, 3 = Unreliable substitute value

A webhook connection can also tell you when the consent of a meter changes, so your system no longer has to poll the meter status through the REST API.

Event Sent when
meter.consent_pending_user the grid operator has acknowledged the request and the customer still has to approve it in the grid operator portal
meter.consent_approved the consent has been approved and the meter is connected
meter.consent_rejected the request has been rejected: by the grid operator, by the customer in the portal, or because the customer did not approve it in time
meter.consent_revoked the consent ends: the customer revoked it, the grid operator ended it, or your disconnect has been confirmed. Sent once, as soon as the end is known

When a connected meter switches to a different data scope, the new request sends meter.consent_pending_user and, if it is refused, meter.consent_rejected. The meter stays connected throughout, and consent_process_state in the payload shows connected. Completing the switch sends no meter.consent_approved. Historical data requests send no events.

A connection receives the events it has subscribed to for every meter of your team, including meters that are not assigned to it. Pick the events under Consent events when you create or edit the connection; with none selected, the connection receives measurement data only. Through the REST API, set the subscribed_events field.

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": "Heat pump",
        "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/approve/1"
}
Field Description
event_id Stays the same on every retry of one event; use it to drop duplicates
occurred_at When the consent changed; events can arrive out of order, so sort a meter's events by this field
smart_meter.id The meter's ID, as in the REST API
smart_meter.consent_process_state The meter's status right after the change, such as connected, ended or not_connected
location_id, customer_id Location and customer IDs from the REST API; customer_id is null if the location has no customer
portal_url Only on meter.consent_pending_user: the grid operator portal link, null if the operator sent none
consent_end_date Only on meter.consent_revoked: the last day the consent covers. Data for that day still arrives; the meter stays connected until it has passed, and no further event follows

Events are signed like measurement deliveries and appear in the connection's delivery log with their event and 0 records. A failed event never switches the connection off, and a delivered one does not clear a measurement delivery problem.

Test a Connection

Click Send Test to send a test delivery with a sample payload to your URL. The response status code is displayed immediately. A 2xx response is considered successful.

For experts

HMAC Signature Verification

Webhooks are signed by the Standard Webhooks scheme, so any Standard Webhooks library can verify them with your signing secret. Every request carries three headers:

Header Content
webhook-id The delivery's ID; stays the same on every retry and when you send a delivery again
webhook-timestamp Unix timestamp of this attempt, in seconds
webhook-signature v1, followed by the base64-encoded HMAC-SHA256 of {webhook-id}.{webhook-timestamp}.{body}

The HMAC key is the part of the signing secret after whsec_, base64-decoded. Compare signatures with a timing-safe comparison and reject timestamps that are too old to guard against replays.

To change the signing secret, click Rotate secret next to it. Until you click Remove previous secret, each request carries a signature for both secrets, separated by a space, so your receiver keeps accepting requests while you switch it to the new secret.

Retry Behaviour

A delivery is retried up to 3 times with a growing pause when your endpoint answers 5xx or 429 or does not answer within the timeout (at most 30 seconds). A Retry-After header sets the pause. Any other response fails at once, redirects included, as they aren't followed.

If deliveries keep failing for an hour, your team gets a notice and the connection stays on. After 72 hours without a successful delivery, or at once when your endpoint answers 410 Gone, the connection is switched off and your team gets a second notice. The next successful delivery ends the failure period. A failed delivery can be sent again with Send again in the delivery log, see Delivery Logs & Errors.