Inkomende Webhooks

Stopzetting van de verouderde webhook op 30 september 2026: de verouderde inkomende webhook, die gegevens post naar een URL van de vorm https://hooks.energyid.eu/services/WebhookIn/{integrationId}/{webhookKey}, stopt op 30 september 2026 om 23:59 (Belgische tijd). Na die datum worden gegevens die naar de oude URL worden gestuurd niet langer aanvaard. Gebruikt uw integratie nog zo'n URL, migreer dan naar de webhook die op deze pagina wordt beschreven. De migratie-FAQ onderaan beantwoordt de meest gestelde vragen.

Deze handleiding helpt ontwikkelaars om hun apparaten te integreren met EnergyID via webhooks. Webhooks stellen uw apparaten in staat om meetgegevens rechtstreeks naar EnergyID te sturen.

Hier volgt een stapsgewijze uitleg over het gebruik van de EnergyID webhooks:

  1. Provisioneringsgegevens: Genereer een provisioning key en secret, die op het apparaat worden opgeslagen. Meerdere apparaten kunnen dezelfde provisioneringsgegevens gebruiken zolang elk apparaat binnen dezelfde provisioneringsfleet een unieke identifier heeft.

  2. Apparaat-provisioning: Het apparaat neemt contact op met EnergyID via het endpoint https://hooks.energyid.eu/hello met de provisioning key en secret, samen met zijn unieke identifier.

    • Apparaatregistratie: Als het apparaat nog niet geregistreerd is bij EnergyID, retourneert het /hello endpoint een WebhookClaimInfo object met een claimcode en URL. Deze URL moet worden weergegeven op de configuratiepagina van het apparaat, zodat de gebruiker erop kan klikken om het apparaat te koppelen aan zijn EnergyID-dossier. Het apparaat moet het /hello endpoint periodiek bevragen (bv. elke 30 seconden) totdat het antwoord overschakelt naar het gekoppelde formaat.

    • Webhook-informatie: Zodra het apparaat is gekoppeld, retourneert het /hello endpoint een WebhookConnectionInfo object. Dit bevat de webhook-URL, de vereiste HTTP-headers (inclusief een autorisatietoken), het webhookbeleid en informatie over het gekoppelde EnergyID-dossier.
      • Het uploadInterval is een waarde in seconden en hangt af van het EnergyID-abonnement van de gebruiker:
        • Gratis: 86400 seconden (24 uur)
        • Premium: 900 seconden (15 minuten)
        • Real-time Add-on: 60 seconden
  3. Gegevens versturen: Zodra het apparaat toegang heeft tot de webhook, kan het meetgegevens versturen naar de opgegeven webhook-URL. Neem alle headers op die tijdens de apparaat-provisioning zijn ontvangen, exact zoals ze zijn ontvangen. Gegevens kunnen worden verstuurd als een enkel JSON-object of als een JSON-array van objecten voor batchuploads.

Verbindingsinformatie bijwerken: Het autorisatietoken in de verbindingsinformatie is 48 uur geldig en moet regelmatig worden vernieuwd. We raden aan het /hello endpoint elke 24 uur te bevragen om het token te vernieuwen en te controleren op wijzigingen in het webhookbeleid. Alle opgeslagen waarden (webhook-URL, authorization, x-twin-id) moeten bij elke vernieuwing worden bijgewerkt, aangezien elk ervan kan wijzigen.
Als het apparaat een HTTP 401 antwoord ontvangt bij het versturen van gegevens, betekent dit dat het token verlopen is en onmiddellijk vernieuwd moet worden door /hello opnieuw aan te roepen.

Apparaat-provisioning

Endpoint:

POST https://hooks.energyid.eu/hello

Headers:

  • X-Provisioning-Key: Uw provisioning key.
  • X-Provisioning-Secret: Uw provisioning secret.

Parameters:

  • deviceId: Unieke identifier (binnen de app-fleet) voor het apparaat.
  • deviceName: Leesbare naam van het apparaat.
  • firmwareVersion (optioneel): Firmwareversie.
  • ipAddress (optioneel): Lokaal IP-adres.
  • macAddress (optioneel): MAC-adres.
  • localDeviceUrl (optioneel): URL voor apparaatconfiguratie in het lokale netwerk.

Voorbeeld

POST https://hooks.energyid.eu/hello

{
  "deviceId": "00000000-0000-0000-0000-000000000000",
  "deviceName": "My device"
}

Claim-antwoord

{
  "claimCode": "4H7A70",
  "claimUrl": "https://app.energyid.eu/integrations/webhook-in/new?code=4H7A70",
  "exp": 1691402519
}

Wanneer een apparaat een claim-antwoord ontvangt, moet het de claimUrl aan de gebruiker tonen en het /hello endpoint regelmatig blijven bevragen (bv. elke 30 seconden) totdat het antwoord een webhookUrl bevat, wat aangeeft dat het apparaat is gekoppeld.

Webhook-informatie-antwoord

{
  "webhookUrl": "https://hooks.energyid.eu/webhook-in",
  "headers": {
    "authorization": "SharedAccessSignature sr=...",
    "x-twin-id": "00000000-0000-0000-0000-000000000000"
  },
  "webhookPolicy": {
    "uploadInterval": 60
  },
  "recordName": "My home",
  "recordNumber": "EA-12345678"
}

De recordName en recordNumber identificeren het EnergyID-dossier waaraan het apparaat is gekoppeld. Deze kunnen aan de gebruiker worden getoond ter bevestiging.

Gegevens versturen

Zodra het apparaat een webhook-URL heeft ontvangen, kan het beginnen met het versturen van gegevens. Stuur hiervoor een POST-verzoek naar de webhook-URL en neem alle headers op die tijdens de apparaat-provisioning zijn ontvangen. Geef de authorization en x-twin-id headers exact door zoals ontvangen van /hello. Decodeer, hercodeer of wijzig ze niet.

Gegevens moeten worden verstuurd als een eenvoudig key-value JSON-object. De ts key, die de timestamp van de metingen voorstelt als een Unix-timestamp (in seconden), is het enige verplichte veld.

Andere keys vertegenwoordigen het ID van een specifieke metriek of sensor van het apparaat en hun bijbehorende waarden. Sommige keys zijn voorgedefinieerd door EnergyID, zoals beschreven in de onderstaande lijst.

Bij gebruik van deze voorgedefinieerde eigenschappen (zoals 'gas', 'pv', 'el') herkent EnergyID automatisch het type meter of sensor dat ze vertegenwoordigen. Gegevens die met deze keys worden verstuurd, zijn onmiddellijk zichtbaar en correct gecategoriseerd zonder extra configuratie.

U kunt ook andere keys kiezen, maar aangezien EnergyID niet weet wat deze datapunten voorstellen, moet de gebruiker deze informatie specificeren voordat de gegevens zichtbaar worden in EnergyID.

Voorgedefinieerde keys kunnen ook als prefix worden gebruikt (gescheiden door een punt) wanneer er meerdere datapunten van hetzelfde type aanwezig zijn.

Enkele meting

POST {webhookUrl}

{
  "ts": 1733835004,
  "gas": 1594.78,
  "pv": 35461.45,
  "el.t1": 11250,
  "el-i.t1": 1545,
  "el.t2": 8944,
  "el-i.t2": 6577,
  "my-custom-sensor": 544.22
}

Batchupload (JSON-array)

Gegevens kunnen ook worden verstuurd als een JSON-array van objecten. Dit is de aanbevolen aanpak voor apparaten die frequent metingen verzamelen, aangezien het het aantal API-aanroepen vermindert en rate limits voorkomt.

POST {webhookUrl}

[
  { "ts": 1733834704, "el": 12345.67, "pv": 3.10 },
  { "ts": 1733834764, "el": 12346.12, "pv": 3.25 },
  { "ts": 1733834824, "el": 12346.89, "pv": 3.40 }
]

Best practice voor batching: Verzamel sensormetingen in een buffer en verstuur ze als een JSON-array op een interval dat overeenkomt met het uploadInterval uit het /hello antwoord. Dit voorkomt 429 rate limit fouten en is efficienter dan elke meting afzonderlijk te versturen.

Voorgedefinieerde eigenschappen

Eigenschap Metriek Type meting Eenheid
el Elektriciteitsafname Cumulatief kWh
el-i Elektriciteitsinjectie Cumulatief kWh
pwr Afnamevermogen net Momentaan kW
pwr-i Injectievermogen net Momentaan kW
gas Aardgasverbruik Cumulatief m³
pv Zonne-energieproductie Cumulatief kWh
wind Windproductie Cumulatief kWh
chp WKK-productie Cumulatief kWh
dh Stadsverwarming Cumulatief kWh
dc Stadskoeling Cumulatief kWh
sol Zonnewarmteproductie Cumulatief kWh
ev Elektrisch voertuig laden Cumulatief kWh
ev-i Elektrisch voertuig ontladen Cumulatief kWh
bat Batterij laden Cumulatief kWh
bat-i Batterij ontladen Cumulatief kWh
bat-soc Batterij laadtoestand Momentaan %
heat Finaal warmteverbruik Cumulatief kWh
dw Drinkwater Cumulatief l

Foutafhandeling

Het is een goede praktijk om rekening te houden met scenario's waarin het versturen van gegevens kan mislukken. Inkomende webhooks kunnen fouten retourneren bij ongeldige verzoeken, verlopen referenties, of wanneer iets uitzonderlijks ons verhindert uw gegevens op te slaan.

HTTP-status Korte beschrijving
200 OK Gegevens succesvol geaccepteerd.
201 Created Gegevens succesvol aangemaakt.
400 Bad Request De payload in uw verzoek kan niet worden begrepen of is ongeldig. Controleer of de JSON geldig is en of het ts veld aanwezig is in elk object.
401 Unauthorized Het autorisatietoken is verlopen. Het moet onmiddellijk worden vernieuwd door het /hello endpoint opnieuw aan te roepen.
403 Forbidden De webhook gekoppeld aan uw verzoek is uitgeschakeld.
404 Not Found De webhook-URL bestaat niet of is niet langer beschikbaar.
429 Too Many Requests Rate limit overschreden. Controleer de Retry-After header voor het aantal seconden dat u moet wachten. Overweeg gegevens te bundelen en minder frequent te versturen.

Rate limiting

De API hanteert rate limits om eerlijk gebruik te garanderen. Als uw apparaat te veel verzoeken stuurt in een korte periode, antwoordt de server met een HTTP 429 Too Many Requests fout.

Wanneer dit gebeurt, controleer de Retry-After HTTP-header in het antwoord. Deze header bevat het aantal seconden dat u moet wachten voordat u een nieuw verzoek stuurt. Om deze limiet te vermijden, bundel uw metingen in een JSON-array en verstuur ze op een interval dat overeenkomt met het uploadInterval uit het /hello antwoord.

Voorbeelden

Werkende integratievoorbeelden zijn beschikbaar in de demos-map van de Python-bibliotheek:

  • cURL / bash: curl_examples.sh - Volledige flow in raw HTTP: authenticatie, enkele meting versturen, batch versturen, token vernieuwen.
  • Node-RED: nodered_flow.json - Importeerbare flow met authenticatie, claim-retry, enkel versturen, batch-buffering en multi-device ondersteuning.
  • Python: Installeer pip install energyid-webhooks en bekijk de snelle demo-notebook of de volledige demo-notebook.

Migreren van de verouderde webhook

De verouderde inkomende webhook (V1/V2/V3) stopt op 30 september 2026 om 23:59 (Belgische tijd). Alles wat u nodig hebt voor de migratie staat al op deze pagina; deze FAQ zet de stappen op een rij.

Hoe weet ik of ik de verouderde webhook gebruik?
Een verouderde integratie post naar https://hooks.energyid.eu/services/WebhookIn/{integrationId}/{webhookKey}. De huidige webhook post naar de URL die /hello teruggeeft, samen met de teruggegeven headers. Sinds augustus 2026 bevat elk antwoord van het verouderde endpoint ook de HTTP-headers Deprecation en Sunset, die de stopzetting aankondigen.

Wat moet ik aanpassen?
Drie dingen. Provisioneer uw apparaat eenmalig via /hello en claim het op uw dossier (zie Apparaat-provisioning hierboven). Stuur uw metingen naar de teruggegeven webhook-URL met de teruggegeven headers. En zet de payload om naar het huidige formaat: een JSON-object of -array met een Unix-ts en één key per metriek (zie Gegevens versturen hierboven).

Heb ik nieuwe inloggegevens nodig?
Ja. De verouderde URL en webhook key zijn niet geldig op de huidige webhook. Activeer de integratie Inkomende Webhook op uw dossier om een provisioning key en secret te verkrijgen, en volg daarna de provisioning-flow hierboven. De oude integratie mag actief blijven tijdens de overgang; schakel ze uit zodra de nieuwe integratie gegevens levert.

Wat gebeurt er met mijn meters en historische meterstanden?
Er wordt niets verwijderd. Uw dossier, meters en historische meterstanden blijven beschikbaar. De huidige webhook registreert zijn eigen kanalen; gebruik de voorgedefinieerde keys (el, gas, pv, ...) zodat ze automatisch herkend en gecategoriseerd worden.

Kan ik de nieuwe webhook gegevens laten sturen naar mijn oude meter?
Nee. De huidige webhook levert zijn metingen altijd aan zijn eigen meters en kan niet schrijven naar een meter die door de verouderde webhook werd aangemaakt. Uw oude meter behoudt zijn historiek, en de nieuwe meter neemt het over vanaf de eerste meting die binnenkomt. Om dubbeltellingen in uw rapporten te vermijden, stelt u de verwerkingsperiode van de oude meter in tot de datum van de eerste meting op de nieuwe meter. Hoe u dat doet, leest u in Een manuele en automatische meter combineren. Die stappen gelden op dezelfde manier voor uw oude webhookmeter.

Wat gebeurt er na 30 september 2026?
Het verouderde endpoint aanvaardt geen gegevens meer en verzoeken ernaar mislukken; verder verandert er niets aan uw dossier. Voor hulp bij de migratie kunt u contact opnemen met support@energieid.be. Vermeld daarbij uw dossiernummer (EA-...).

Apps bouwen

Hardwareleveranciers en cloud-to-cloud dataproviders kunnen hun eigen integratie aanbieden in de EnergyID App Directory. Dit zorgt voor een gestroomlijnde gebruikerservaring.

In plaats van standaard gebruikersgegevens ontvangen partners een specifieke Device Provisioning Key en Secret. Deze zijn gekoppeld aan een specifiek endpoint voor uw applicatie, wat een robuuste en schaalbare oplossing biedt voor uw gebruikers. Neem contact op met info@energieid.be voor meer informatie over het worden van een integratiepartner.