La nouvelle version de notre Webhook Entrant est actuellement en version préliminaire.

Cette page a été traduite de l'anglais. Certains termes techniques et abréviations restent en anglais pour maintenir la cohérence technique. Consulter la version originale en anglais.

Ce guide est conçu pour aider les développeurs à intégrer leurs appareils avec EnergyID en utilisant des webhooks. Les webhooks permettent à vos appareils d'envoyer directement des données de mesure à EnergyID.

Voici une explication étape par étape sur l'utilisation des webhooks EnergyID :

1. Informations d'Approvisionnement : Générez une clé et un secret d'approvisionnement, qui sont stockés sur l'appareil. Plusieurs appareils peuvent utiliser les mêmes informations d'approvisionnement tant que tous les appareils au sein de la même flotte d'approvisionnement ont un identifiant unique.

2. Approvisionnement de l'Appareil : L'appareil contacte EnergyID au point de terminaison https://hooks.energyid.eu/hello en utilisant la clé et le secret d'approvisionnement, ainsi que son identifiant unique.

   • Enregistrement de l'Appareil : Si l'appareil n'est pas encore enregistré auprès d'EnergyID, le point de terminaison /hello renverra un objet WebhookClaimInfo contenant un code de réclamation et une URL. Cette URL doit être affichée sur la page de configuration de l'appareil, permettant à l'utilisateur de cliquer dessus et de lier l'appareil à son compte EnergyID.

   • Informations du Data Hub : Une fois que l'appareil a été réclamé, le point de terminaison /hello renverra un objet WebhookConnectionInfo. Celui-ci contient l'URL du webhook, les en-têtes HTTP requis (y compris un jeton d'autorisation), et l'intervalle d'envoi autorisé pour l'envoi de données au Data Hub d'EnergyID.
3. Envoi de Données : Une fois que l'appareil a accès au Data Hub, il peut commencer à envoyer des données de mesure à l'URL du webhook fournie. Assurez-vous d'inclure les en-têtes HTTP requis dans chaque requête.

Mise à jour des Informations de Connexion : Le jeton d'autorisation inclus dans les informations de connexion est valide pendant 48 heures et doit être actualisé régulièrement. Nous recommandons d'interroger le point de terminaison /hello toutes les 24 heures pour renouveler le jeton et vérifier tout changement dans la politique du webhook.
Si l'appareil reçoit une réponse HTTP 401 lors de l'envoi de données, cela indique que le jeton a expiré et doit être renouvelé immédiatement.

Approvisionnement de l'Appareil

Point de terminaison :

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

En-têtes :

• X-Provisioning-Key : Votre clé d'approvisionnement.
• X-Provisioning-Secret : Votre secret d'approvisionnement.

Paramètres :

• deviceId : Identifiant unique (au sein de la flotte d'applications) pour l'appareil
• deviceName : Nom d'appareil lisible par l'humain.
• firmwareVersion (optionnel) : Version du firmware.
• ipAddress (optionnel) : Adresse IP locale.
• macAddress (optionnel) : Adresse MAC.
• localDeviceUrl (optionnel) : URL pour la configuration de l'appareil sur le réseau local.

Exemple

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

{
  "deviceId": "<DEVICE_ID>",
  "deviceName": "Mon appareil"
}

Réponse de réclamation

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

Réponse d'informations du Data Hub

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

Envoi de Données

Une fois que l'appareil reçoit une URL de webhook, il peut commencer à envoyer des données. Pour ce faire, envoyez une requête POST à l'URL du webhook et incluez tous les en-têtes retournés lors du processus d'approvisionnement de l'appareil.

Les données doivent être envoyées dans un objet JSON clé-valeur simple. La clé ts (timestamp), qui représente l'horodatage des mesures sous forme de timestamp Unix (en secondes), est la seule clé requise.

Les autres clés représentent l'ID d'une métrique ou d'un capteur spécifique mesuré par l'appareil et leurs valeurs correspondantes. Certaines clés sont prédéfinies par EnergyID, comme décrit dans la liste ci-dessous.

Lorsque vous utilisez ces propriétés prédéfinies (comme 'gas', 'pv', 'el'), EnergyID reconnaît automatiquement le type de compteur ou de capteur qu'elles représentent, de sorte que les données envoyées avec ces clés seront immédiatement visibles et correctement catégorisées sans configuration supplémentaire.

Vous pouvez choisir d'autres clés, mais comme EnergyID ne sait pas ce que ces points de données représentent, l'utilisateur devra spécifier ces informations avant que les données ne deviennent visibles dans EnergyID.

Les clés prédéfinies peuvent également être utilisées comme préfixes (séparés par un point) lorsque plusieurs points de données du même type sont présents. Les données peuvent être envoyées soit comme un seul objet, soit comme une liste d'objets.

Exemple

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
}

Propriétés Prédéfinies