This tutorial will deal with the configuration of a webhook for Smarther – v2.0 API. Webhooks allows you to subscribe to events. You can store your data on the endpoint you defined and, once the webhook triggered, getting notified when an event occurs

Prerequisite

Important

  • Only HTTPS webhook endpoint request are supported
  • Your Ocp-Apim-Subscription-Key is personal and must remain confidential

Send a webhook registration and subscription request

To register your webhook URL and subscribe to device events for a specific plant, the application must perform a POST HTTPS request to the following URL:

https://api.developer.legrand.com/smarther/v2.0/plants/{plantId}/subscription

With the following information in the header:

NameDescription
Content-TypeValue is : “Application/json”
Ocp-Apim-Subscription-KeySubscription key which provides access to this API. Found in the page My Subscriptions
AuthorizationOAuth2 access_token retrieved from your refresh token flow

With the following parameters in the body:

{
“EndPointUrl”: “<webhookUrl>”
}

Possible values of change

ValueExplanationC2C notification examples
FunctionCurrent thermostat function{
“chronothermostats”: [{
“function”: “HEATING”,
“mode”: “MANUAL”,
“setPoint”: {
“value”: “19.1”,
“unit”: “C”
},
“programs”: [{
“number”: “1”
}],
“activationTime”: “2019-11-17T02:00:47Z”,
“temperatureFormat”: “C”,
“loadState”: “INACTIVE”,
“time”: “2019-01-24T15:30:20Z”,
“thermometer”: {
“measures”: [{
“timeStamp”: “2019-01-24T15:30:19Z”,
“value”: “24.6”,
“unit”: “C”
}]
},
“hygrometer”: {
“measures”: [{
“timeStamp”: “2019-01-24T15:30:19Z”,
“value”: “24.6”,
“unit”: “%”
}]
},
“sender”: {
“addressType”: “AddressLocation”,
“system”: “thermoregulation”,
“plant”: {
“id”: “b5e48d6f-cbad-2711-e053-27182d0ad74c”,
“module”: {
“id”: “1ee68d6f-46b7-8f11-e053-27182d0a846a”
}
}
},
“receiver”: {
“oid”: [“a122e653-53fb-450e-b000-d47659807585”]
}
}]
},
ModeCurrent thermostat working mode
Setpoint temperatureCurrent thermostat setpoint temperature, if working mode is not boost
Program numberCurrent thermostat active program number, if working mode is automatic
Activation timeDate and time to which current working mode will be maintained
Load stateCurrent thermostat load state
Measured temperature / humidityOperation used to retrieve the measured temperature and humidity detected by a chronothermostat

Warning

  • If a webhook doesn’t reply, a retry will be sent following this schedule: 10 seconds, 30 seconds, 1 minute, 5 minutes and 10 minutes
  • All events not delivered in a period of 24 hours are considered has expired and will not be delivered
  • A user can have several webhooks for the same plant (number of webhooks allowed could change over the time)
  • A webhook can be banned if it doesn’t respond in less than 750ms or respond with a code >= 300. In this case, we increment a failure counter. After 20 failures, we count 1 error for your endpoint and ban it for a total of minutes calculated as following: 1 minute * set of 20 failures (i.e. : 200 failures = 10 minutes ban). The maximum ban time is 20 minutes. All webhook changes that happened during this ban are lost and will not be sent