Dit artikel helpt ontwikkelaars bij het koppelen van hun apparaten aan EnergieID via Inkomende Webhooks. Met deze webhooks kunnen meetgegevens direct naar EnergieID worden gestuurd.

Sinds begin 2025 is er een nieuwe versie van de Inkomende Webhooks beschikbaar, met een vernieuwde manier van provisioning en het versturen van gegevens.

Hier volgt een stap-voor-stap uitleg over het gebruik van de Inkomende Webhooks:

1. Provisioning credentials: Genereer een provisioning key en secret, die op het apparaat worden opgeslagen. Meerdere apparaten kunnen dezelfde credentials gebruiken, mits elk apparaat binnen dezelfde provisioning fleet een unieke identifier heeft.

2. Apparaat provisioning: Het apparaat maakt verbinding met EnergieID via het endpoint https://hooks.energyid.eu/hello, met de provisioning key, secret en zijn unieke identifier.

   • Apparaatregistratie (claiming) — Als het apparaat nog niet bij EnergieID is geregistreerd, retourneert het /hello endpoint een WebhookClaimInfo object met een claimcode en claim-URL. Toon deze URL in de configuratie-interface van het apparaat, zodat de gebruiker erop kan klikken en het apparaat kan koppelen aan zijn EnergieID-dossier.

   • Verbindingsgegevens (na claiming) — Zodra het apparaat is geclaimd, retourneert het /hello endpoint een WebhookConnectionInfo object. Dit bevat de webhook-URL, de vereiste HTTP-headers (inclusief een autorisatietoken), en het toegestane uploadinterval voor het versturen van gegevens naar EnergieID.

     Het uploadinterval is een waarde in seconden en is afhankelijk van het EnergieID-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 gekregen tot de webhook, kunnen meetgegevens worden doorgestuurd naar de opgegeven webhook-URL. Let erop dat bij elk verzoek alle vereiste HTTP-headers worden meegestuurd.

Verbindingsgegevens bijwerken: Het autorisatietoken dat is opgenomen in de verbindingsgegevens is 48 uur geldig en moet regelmatig worden vernieuwd. We raden aan om het /hello endpoint elke 24 uur te pollen om het token te vernieuwen en eventuele wijzigingen in het webhookbeleid te controleren.
Als het apparaat een HTTP 401-antwoord ontvangt bij het versturen van gegevens, betekent dit dat het token is verlopen en onmiddellijk moet worden vernieuwd.

Apparaat provisioning

Endpoint:

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

Headers:

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

Parameters:

• deviceId: Unieke identifier (binnen de app fleet) voor het apparaat.
• deviceName: Menselijk leesbare apparaatnaam.
• firmwareVersion (optioneel): Firmware versie.
• 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": "Mijn apparaat"
}

Webhook Claim Info

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

Webhook Connection Info

{
  "webhookUrl": "https://hooks.energyid.eu/webhook-in",
  "headers": {
    "authorization": "Bearer ",
    "x-twin-id": "00000000-0000-0000-0000-000000000000"
  },
  "webhookPolicy": {
    "uploadInterval": 60
  }
}

Gegevens versturen

Zodra het apparaat een webhook-URL van EnergieID ontvangt, kunnen gegevens naar EnergieID worden gestuurd. Dit gebeurt door een POST-verzoek te sturen naar de webhook-URL, inclusief alle headers die tijdens het provisioningproces van het apparaat zijn ontvangen.

De gegevens moeten in een eenvoudig JSON-object met key-value-paren worden aangeleverd. De key ts, die de tijdstempel van de metingen als Unix-timestamp (in seconden) bevat, is de enige verplichte key. Andere keys geven de ID van een specifieke metriek of sensor van het apparaat weer, samen met de bijbehorende waarden. Een aantal keys zijn door EnergieID vooraf gedefinieerd, zoals beschreven in de onderstaande lijst.

Bij gebruik van deze voorgedefinieerde keys (zoals gas, pv, el) herkent EnergieID automatisch welke metriek ze vertegenwoordigen. Gegevens die met deze keys worden verstuurd, zijn daardoor direct zichtbaar en correct gecategoriseerd, zonder extra configuratie. 

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

Je kunt ook andere keys gebruiken, maar omdat EnergieID niet weet welke datapunten ze vertegenwoordigen, moet de gebruiker deze informatie zelf opgeven voordat de gegevens zichtbaar worden in EnergieID. 

Gegevens kunnen worden verstuurd als één enkel JSON-object of als een lijst van objecten.

Voorbeeld

POST

{
  "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
}

Voorgedefinieerde properties

Foutafhandeling

Het is een goede gewoonte om voorbereid te zijn op scenario's waarin het verzenden van een payload mislukt. Inkomende webhooks kunnen fouten retourneren bij onjuist geformatteerde verzoeken, ongeldige credentials, of wanneer iets uitzonderlijks ons verhindert je meetgegevens op te slaan.

Rate limiting

De API past rate limits toe om eerlijk gebruik te garanderen. Als je apparaat te veel verzoeken in een korte periode verstuurt, zal de server antwoorden met een HTTP 429 Too Many Requests-fout.

Wanneer dit gebeurt, controleer dan de Retry-After HTTP-header in de respons. Deze header bevat het aantal seconden dat je moet wachten voordat je een nieuw verzoek kunt doen. Om te voorkomen dat je deze limiet bereikt, is het een goede gewoonte om gegevens te bundelen en je proces minder frequent uit te voeren, bijvoorbeeld elke 15 minuten.

Apps bouwen

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

In plaats van standaard gebruikersreferenties te gebruiken, ontvangen partners een speciale Device Provisioning Key en Secret. Deze zijn gekoppeld aan een specifiek endpoint voor hun applicatie, wat een robuuste en schaalbare oplossing voor hun gebruikers biedt. Neem contact met ons voor meer informatie over hoe je een integratiepartner kunt worden.