Tutorials

Subscription to Cloud to Cloud notifications (C2C webhooks)

This tutorial will deal with the configuration of a webhook for Home + Control API and 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


For Home + Control API


Step 1 : Implement webhook verification

The webhook verification can be done at any time and mainly to validate the registration request
To verify your endpoint, you receive in a POST request a special event containing a verification code:

[{
"id": "17dcee11-b3ad-44e5-b381-f44079499577",
"data": {
"validationCode": "7d4b4c96-4964-4763-abdd-b9a1efdef632"
},
"eventType": "Microsoft.EventGrid.SubscriptionValidationEvent",
"eventTime": "2019-03-09T15:25:52.83003Z",
}]

 

You just have to reply with the verification code:

{
"validationCode": "7d4b4c96-4964-4763-abdd-b9a1efdef632"
}


Step 2 : Send a webhook registration request

In order to register your webhook, please use the Home + Control Webhook registration contact form by clicking on this link. Once you received a confirmation email informing you that the registration is done, you can go to Step 3


Step 3 : Subscribe to events

For subscribing to device events for a specific plant, the application must perform a POST HTTPS request to the following URL:

https://api.developer.legrand.com/hc/api/v1.0/addsubscription

 

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:

{
"plantid": "YourPlantID"
}

 

Possible values of change
ValueExplanationC2C notification examples
Connection / disconnectionGateway (dis)connected[{
"eventType": "DeviceToCloud",
"data": {
"change": "topology",
"sender": {
"plant": {
"id": "000000005a0c58b3b4809d521d8b4bd9"
}
},
"timestamp": "2018-06-12T06:54:24.948Z"
}
}][{
"eventType": "DeviceToCloud",
"data": {
"change": "state",
"sender": {
"plant": {
"id": "000000005a0c58b3b4809d521d8b4bd9",
"module": {
"id": "000000047d217ace0000000000000000"
}
}
},
"timestamp": "2018-07-08T02:05:27.000Z"
}
}]
Forgotten_lightForgotten light (stayed “on” for a long time, according to the configuration in the Home + Control application)
StateScene launched (home / away / wake up / sleep)Scene launching retrieved code (last digits):

'0000000000000000': 'Away'
'0000000000000001': 'Home'
'0000000000000002': 'Wake-up'
'0000000000000003': 'Bedtime'

 

Warning

  • A webhook must reply in less than 500 milliseconds
  • After 5 errors (HTTP code >= 4xx or timeout) in less than 120 seconds, the webhook is banned for 300 seconds (value could change over the time)
  • There’s no guarantee that an event will be re-sent if the webhook is unavailable or temporarily banned
  • If a webhook already exist for a plant, creating a new one will erase the previous one


For Smarther API


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
(Optional) 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)