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

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.

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.

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.