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 zijn EnergyID-dossier kan koppelen.

   • Webhook 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 EnergyID.
     • Het uploadInterval is een waarde in seconden en is afhankelijk 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 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 het webhook-beleid te controleren.
Als het apparaat een HTTP 401-respons 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": "",
  "deviceName": "Mijn apparaat"
}

Claim response

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

Webhook informatie response

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

{
  "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 uw meetgegevens op te slaan.

Rate Limiting

De API past rate limits toe om eerlijk gebruik te garanderen. Als uw 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 u moet wachten voordat u een nieuw verzoek kunt doen. Om te voorkomen dat u deze limiet bereikt, is het een goede gewoonte om gegevens te bundelen en uw 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 uw applicatie, wat een robuuste en schaalbare oplossing voor uw gebruikers biedt. Neem contact met ons op via info@energieid.be voor meer informatie over hoe u een integratiepartner kunt worden.