Deze pagina werd vertaald vanuit het Engels. Sommige technische termen en afkortingen blijven in het Engels om de technische consistentie te behouden. Bekijk de originele Engelstalige versie.

De nieuwe versie van onze Inkomende Webhook is momenteel in preview.

Deze handleiding is ontworpen om ontwikkelaars te helpen bij het integreren van hun apparaten met EnergyID via webhooks. Webhooks stellen je apparaten in staat om meetgegevens rechtstreeks naar EnergyID te sturen.

Hier volgt een stap-voor-stap uitleg over het gebruik van de EnergyID webhooks:

1. Provisioning Credentials: Genereer een provisioning key en secret, die op het apparaat worden opgeslagen. Meerdere apparaten kunnen dezelfde provisioning credentials gebruiken zolang alle apparaten binnen dezelfde provisioning fleet een unieke identifier hebben.

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

   • Apparaat Registratie: Als het apparaat nog niet bij EnergyID is geregistreerd, zal het /hello endpoint een WebhookClaimInfo object terugsturen met een claim code en URL. Deze URL moet worden weergegeven op de configuratiepagina van het apparaat, zodat de gebruiker erop kan klikken en het apparaat aan hun EnergyID record kan koppelen.

   • Data Hub Informatie: Zodra het apparaat is geclaimd, zal het /hello endpoint een WebhookConnectionInfo object terugsturen. Dit bevat de webhook URL, de vereiste HTTP headers (inclusief een autorisatie token), en het toegestane upload interval voor het versturen van gegevens naar de EnergyID Data Hub.
3. Gegevens Versturen: Zodra het apparaat toegang heeft tot de Data Hub, kan het beginnen met het versturen van meetgegevens naar de verstrekte webhook URL. Zorg ervoor dat alle vereiste HTTP headers in elke request worden opgenomen.

Verbindingsgegevens Bijwerken: Het autorisatie token 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 webhook beleid te controleren.
Als het apparaat een HTTP 401 response 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": "<DEVICE_ID>",
  "deviceName": "Mijn apparaat"
}

Claim response

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

Data-hub informatie response

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

Gegevens Versturen

Zodra het apparaat een webhook URL ontvangt, kan het beginnen met het versturen van gegevens. Hiervoor stuur je een POST request naar de webhook URL en voeg je alle headers toe die tijdens het apparaat provisioning proces zijn ontvangen.

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

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

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

Je kunt andere keys kiezen, maar omdat EnergyID niet weet wat deze datapunten voorstellen, zal de gebruiker deze informatie moeten specificeren voordat de gegevens zichtbaar worden in EnergyID.

Voorgedefinieerde keys kunnen ook als prefixen worden gebruikt (gescheiden door een punt) wanneer meerdere datapunten van hetzelfde type aanwezig zijn. Gegevens kunnen worden verstuurd als een enkel object of als een lijst van objecten.

Voorbeeld

POST <webhook URL>

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