Webhook Entrant

Arrêt de l'ancien webhook le 30 septembre 2026 : l'ancien webhook entrant, qui envoie les données vers une URL de la forme https://hooks.energyid.eu/services/WebhookIn/{integrationId}/{webhookKey}, s'arrête le 30 septembre 2026 à 23h59 (heure belge). Après cette date, les données envoyées à l'ancienne URL ne sont plus acceptées. Si votre intégration utilise encore une telle URL, migrez vers le webhook décrit sur cette page. La FAQ de migration ci-dessous répond aux questions les plus fréquentes.

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 des données de mesure directement à EnergyID.

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

Identifiants de provisionnement : Générez une clé et un secret de provisionnement, qui sont stockés sur l'appareil. Plusieurs appareils peuvent utiliser les mêmes identifiants de provisionnement à condition que chaque appareil au sein de la même flotte de provisionnement ait un identifiant unique.
Provisionnement de l'appareil : L'appareil contacte EnergyID au point de terminaison https://hooks.energyid.eu/hello en utilisant la clé et le secret de provisionnement, 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 revendication et une URL. Cette URL doit être affichée sur la page de configuration de l'appareil, permettant à l'utilisateur de cliquer dessus pour lier l'appareil à son dossier EnergyID. L'appareil doit interroger le point de terminaison /hello périodiquement (par ex. toutes les 30 secondes) jusqu'à ce que la réponse passe au format revendiqué.
- Informations du webhook : Une fois l'appareil revendiqué, 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), la politique du webhook et des informations sur le dossier EnergyID lié.
  - L'uploadInterval est une valeur en secondes qui dépend de l'abonnement EnergyID de l'utilisateur :
    - Gratuit : 86400 secondes (24 heures)
    - Premium : 900 secondes (15 minutes)
    - Module temps réel : 60 secondes
Envoi de données : Une fois que l'appareil a accès au webhook, il peut commencer à envoyer des données de mesure à l'URL du webhook fournie. Incluez tous les en-têtes retournés lors du provisionnement de l'appareil exactement tels qu'ils ont été reçus. Les données peuvent être envoyées sous forme d'un objet JSON unique ou d'un tableau JSON d'objets pour les envois par lots.

Mise à jour des informations de connexion : Le jeton d'autorisation inclus dans les informations de connexion est valide pendant 48 heures et doit être renouvelé régulièrement. Nous recommandons d'interroger le point de terminaison /hello toutes les 24 heures pour renouveler le jeton et vérifier les modifications de la politique du webhook. Toutes les valeurs stockées (URL du webhook, authorization, x-twin-id) doivent être mises à jour à chaque renouvellement, car chacune d'entre elles peut changer.
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 en appelant à nouveau /hello.

Provisionnement de l'appareil

Point de terminaison :

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

En-têtes :

X-Provisioning-Key : Votre clé de provisionnement.
X-Provisioning-Secret : Votre secret de provisionnement.

Paramètres :

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

Exemple

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

{
  "deviceId": "00000000-0000-0000-0000-000000000000",
  "deviceName": "My device"
}

Réponse de revendication

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

Lorsqu'un appareil reçoit une réponse de revendication, il doit afficher la claimUrl à l'utilisateur et continuer à interroger le point de terminaison /hello à intervalles réguliers (par ex. toutes les 30 secondes) jusqu'à ce que la réponse contienne un webhookUrl, indiquant que l'appareil a été revendiqué.

Réponse avec informations du webhook

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

Les champs recordName et recordNumber identifient le dossier EnergyID auquel l'appareil a été lié. Ceux-ci peuvent être affichés à l'utilisateur pour confirmation.

Envoi de données

Une fois que l'appareil a reçu une URL de webhook, il peut commencer à envoyer des données. Pour cela, envoyez une requête POST à l'URL du webhook et incluez tous les en-têtes retournés lors du provisionnement. Transmettez les en-têtes authorization et x-twin-id exactement tels qu'ils ont été reçus de /hello. Ne les décodez pas, ne les réencodez pas et ne les modifiez pas.

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

Les autres clés représentent l'identifiant 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.

Lors de l'utilisation de 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. 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.

Mesure unique

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
}

Envoi par lots (tableau JSON)

Les données peuvent également être envoyées sous forme d'un tableau JSON d'objets. C'est l'approche recommandée pour les appareils qui collectent des mesures fréquemment, car cela réduit le nombre d'appels API et évite les limites de débit.

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 }
]

Bonne pratique pour les lots : Collectez les mesures des capteurs dans un tampon et envoyez-les sous forme de tableau JSON à un intervalle correspondant à l'uploadInterval de la réponse /hello. Cela évite les erreurs de limite de débit 429 et est plus efficace que d'envoyer chaque mesure individuellement.

Propriétés prédéfinies

Propriété	Métrique	Type de mesure	Unité
el	Prélèvement d'électricité	Cumulatif	kWh
el-i	Injection d'électricité	Cumulatif	kWh
pwr	Puissance de prélèvement réseau	Instantané	kW
pwr-i	Puissance d'injection réseau	Instantané	kW
gas	Consommation de gaz naturel	Cumulatif	m³
pv	Production photovoltaïque	Cumulatif	kWh
wind	Production éolienne	Cumulatif	kWh
chp	Production de cogénération	Cumulatif	kWh
dh	Chauffage urbain	Cumulatif	kWh
dc	Refroidissement urbain	Cumulatif	kWh
sol	Production de chaleur solaire	Cumulatif	kWh
ev	Charge de véhicule électrique	Cumulatif	kWh
ev-i	Décharge de véhicule électrique	Cumulatif	kWh
bat	Charge de batterie	Cumulatif	kWh
bat-i	Décharge de batterie	Cumulatif	kWh
bat-soc	État de charge de la batterie	Instantané	%
heat	Consommation finale de chaleur	Cumulatif	kWh
dw	Eau potable	Cumulatif	l

Gestion des erreurs

Il est recommandé de prévoir les scénarios où l'envoi de données pourrait échouer. Les webhooks entrants peuvent retourner des erreurs pour des requêtes malformées, des identifiants invalides, ou lorsqu'un problème exceptionnel nous empêche de stocker vos données.

Statut HTTP	Description
200 OK	Données acceptées avec succès.
201 Created	Données créées avec succès.
400 Bad Request	La charge utile de votre requête ne peut pas être comprise ou est malformée. Vérifiez que le JSON est valide et que le champ ts est présent dans chaque objet.
401 Unauthorized	Le jeton d'autorisation a expiré. Il doit être renouvelé immédiatement en appelant à nouveau le point de terminaison /hello.
403 Forbidden	Le webhook associé à votre requête a été désactivé.
404 Not Found	L'URL du webhook n'existe pas ou n'est plus disponible.
429 Too Many Requests	Limite de débit dépassée. Vérifiez l'en-tête Retry-After pour le nombre de secondes à attendre. Envisagez de regrouper les données et d'envoyer moins fréquemment.

Limitation de débit

L'API impose des limites de débit pour garantir une utilisation équitable. Si votre appareil envoie trop de requêtes en peu de temps, le serveur répondra avec une erreur HTTP 429 Too Many Requests.

Lorsque cela se produit, vérifiez l'en-tête HTTP Retry-After dans la réponse. Cet en-tête contient le nombre de secondes à attendre avant d'effectuer une nouvelle requête. Pour éviter d'atteindre cette limite, regroupez vos mesures dans un tableau JSON et envoyez-les à un intervalle correspondant à l'uploadInterval de la réponse /hello.

Exemples

Des exemples d'intégration fonctionnels sont disponibles dans le dossier demos de la bibliothèque Python :

cURL / bash : curl_examples.sh - Flux complet en HTTP brut : authentification, envoi d'une mesure unique, envoi par lots, renouvellement du jeton.
Node-RED : nodered_flow.json - Flux importable avec authentification, nouvelle tentative de revendication, envoi unique, mise en tampon par lots et support multi-appareils.
Python : Installez pip install energyid-webhooks et consultez le notebook de démarrage rapide ou le notebook de démo complet.

Migrer depuis l'ancien webhook

L'ancien webhook entrant (V1/V2/V3) s'arrête le 30 septembre 2026 à 23h59 (heure belge). Tout ce dont vous avez besoin pour la migration se trouve déjà sur cette page ; cette FAQ fait le lien entre les étapes.

Comment savoir si j'utilise l'ancien webhook ?
Une ancienne intégration envoie ses données vers https://hooks.energyid.eu/services/WebhookIn/{integrationId}/{webhookKey}. Le webhook actuel envoie ses données vers l'URL renvoyée par /hello, avec les en-têtes renvoyés. Depuis août 2026, chaque réponse de l'ancien point de terminaison contient aussi les en-têtes HTTP Deprecation et Sunset, qui annoncent l'arrêt.

Que dois-je modifier ?
Trois choses. Provisionnez votre appareil une seule fois via /hello et revendiquez-le sur votre dossier (voir Provisionnement de l'appareil ci-dessus). Envoyez vos mesures à l'URL du webhook renvoyée, avec les en-têtes renvoyés. Et passez au format de payload actuel : un objet ou un tableau JSON avec un ts Unix et une clé par métrique (voir Envoi de données ci-dessus).

Ai-je besoin de nouveaux identifiants ?
Oui. L'ancienne URL et la clé du webhook ne sont pas valides sur le webhook actuel. Activez l'intégration Webhook entrant sur votre dossier pour obtenir une clé et un secret de provisionnement, puis suivez le processus de provisionnement ci-dessus. L'ancienne intégration peut rester active pendant la transition ; désactivez-la dès que la nouvelle fournit des données.

Qu'advient-il de mes compteurs et de mes relevés historiques ?
Rien n'est supprimé. Votre dossier, vos compteurs et vos relevés historiques restent disponibles. Le webhook actuel enregistre ses propres canaux ; utilisez les clés prédéfinies (el, gas, pv, ...) pour qu'ils soient reconnus et catégorisés automatiquement.

Puis-je faire envoyer les données du nouveau webhook vers mon ancien compteur ?
Non. Le webhook actuel transmet toujours ses mesures à ses propres compteurs et ne peut pas écrire dans un compteur créé par l'ancien webhook. Votre ancien compteur conserve son historique, et le nouveau compteur prend le relais à partir de la première mesure reçue. Pour éviter un double comptage dans vos rapports, clôturez l'ancien compteur en indiquant dans Période de traitement à la date de la première mesure du nouveau compteur. La marche à suivre est décrite dans Combiner un compteur manuel et un compteur automatique. Ces étapes s'appliquent de la même manière à votre ancien compteur webhook.

Que se passe-t-il après le 30 septembre 2026 ?
L'ancien point de terminaison n'accepte plus de données et les requêtes vers celui-ci échouent ; rien d'autre ne change dans votre dossier. Pour obtenir de l'aide pour la migration, contactez support@energieid.be en indiquant votre numéro de dossier (EA-...).

Développer des applications

Les fournisseurs de matériel et les fournisseurs de données cloud-to-cloud peuvent proposer leur propre intégration dans le répertoire d'applications EnergyID. Cela permet une expérience utilisateur plus fluide.

Au lieu d'utiliser des identifiants utilisateur standard, les partenaires reçoivent une clé et un secret de provisionnement d'appareil dédiés. Ceux-ci sont liés à un point de terminaison dédié pour votre application, offrant une solution robuste et évolutive pour vos utilisateurs. Contactez-nous à info@energieid.be pour plus d'informations sur le partenariat d'intégration.