Free@home cloud API concepts

Webhooks

Webhooks are a way to receive events from a SysAP via the cloud. A webhook is simply a web page on your server that the free@home cloud will call when the SysAP sends an event. On receival of that event, you can then perform custom actions. This can be seen as a “callback” mechanism.

In order to use webhooks in the free@home cloud API, you have to

1. Have a webhook redirect URL available that the free@home cloud can reach.
   For example a simple PHP page would suffice.

2. Register this URL with the free@home cloud.
   Please note: There is no self-service right now to use webhooks for the free@home API. Please contact us at DE-SmarterHomeDeveloper@abb.com and send us your webhook redirect URL.

3. Subscribe to events using the REST API. This triggers the free@home cloud to call the webhook URL with the events.

4. Whitelist the datapoints that you want to receive. The free@home cloud will send datapoint updates for whitelisted events only. The whitelist is empty by default.

Subscribing to webhook events

The following call can be used to subscribe the webhook for a specific user:

curl -X POST \ 
  -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \ 
  -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' \ 
  -H 'Content-Type: application/json' \ 
  https://apim.eu.mybuildings.abb.com/fhapi/v1/events/subscription \ 
  -d '{}'

On success, this endpoint will respond with a HTTP 200 (success) response and no HTTP body. This means that the webhook has been activated.

In advanced use-cases, if the webhook itself (not the free@home cloud API calls, but rather the webhook implementation) uses OAuth2 as well, the /events/subscription call may contain an authCode parameter:

-d '{ "authCode": "xxxxxxx-User-Scoped-Secret-xxxxxxx" }'

This authCode parameter can be used for that authentication. This is however not required and the parameter is not used by the free@home cloud itself.

NOTE: You also must set a whitelist, otherwise no datapoint updates will be sent by the free@home cloud.

Whitelisting datapoints for webhook events

The free@home system access point manages a lot of datapoint updates, especially when many devices are connected. For example when dimming single a dimmable light, many updates will be sent (at least one per dimming step). However most systems don’t care about most updates and sending all of them to the webhook would be a huge waste of bandwidth and performance.

Therefore, in order to receive datapoint updates, you must install a whitelist first. Only datapoint updates for datapoints that are in the whitelist are ever sent.

An HTTP PUT call to events/whitelist sets a filter which determines which information is of interest. Setting an empty whitelist causes the delivery of no updates.

The call takes a JSON object as request body:

{ 
  "<sysap-uuid>/<dpSerial1>": { 
  "custom data": "needed for recognizing the type of the datapoint", 
  "some more data": "not interpreted by free@home cloud"
  }, 
  "<sysap-uuid>/<dpSerial2>": { 
    "custom data": "needed for recognizing the type of the datapoint" 
  } 
}

For example:

curl -X PUT \ 
  https://apim.eu.mybuildings.abb.com/fhapi/v1/events/whitelist \ 
  -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \ 
  -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN' 
  -H 'Content-Type: application/json' \ 
  -d '{ "86f10d2c-ea8c-11e9-920a-68f728dbd933/FFFFFFFFFFFF/chFFFF/odpFFFF": { "mydeviceid": "afa55e08-ea8c-11e9-86c2-68f728dbd933", "type": "toaster" } }'

Each entry of the whitelist is a key/value pair. The key is a datapoint serial, the value is a JSON object. Note that any JSON object is valid as value, including an empty object “{}”.

The datapoint serial uses the format <SysAP UUID>/<Device ID>/<Channel ID>/<Datapoint ID>. All values can be obtained from a /api/rest/configuration call. Note that the <Channel ID> always starts with ch and the <Datapoint ID> always starts with odp (input datapoints make little sense in webhook events).

See also the API documentation on this call.

Custom data in whitelist values

The JSON object in in each key/value pair of the whitelist may contain your own custom data that helps you to identify the meaning of this datapoint. If your webhook implementation does not need additional data, simply use an empty object (“{}”). In the example above, the whitelist indicates that the device FFFFFFFFFFFF refers to a “toaster” with your (custom) deviceid afa55e08-ea8c-11e9-86c2-68f728dbd933.

The whitelist is sent along with all webhook events that are sent by the free@home cloud, therefore these custom JSON objects may help the webhook to process the data.

Webhook events

A typical webhook call to your host cloud.example.com is an HTTP POST call with the following POST body:

{ 
  "updates": { 
    "2144f07d-1db5-42bb-adec-6da0211b1666": { 
      "datapoints": { 
        "FFFFFFFFFFFF/chFFFF/odpFFFF": "0" 
      }, 
      "timestamp": "2019-08-01T12:07:50.465Z" 
    } 
  }, 
  "whitelist": { 
    "2144f07d-1db5-42bb-adec-6da0211b1666/FFFFFFFFFFFF/chFFFF/odpFFFF": { 
      "mydeviceid": "afa55e08-ea8c-11e9-86c2-68f728dbd933", 
      "type": "toaster" 
    } 
  } 
}

In this example you can see

• The updated datapoints (FFFFFFFFFFFF/chFFFF/odpFFFF) for every SysAP (2144f07d-1db5-42bb-adec-6da0211b1666) with the new values.

• The whitelist that was set by your /events/whitelist request.

Note that the free@home cloud sends updates for the datapoints that are included in the whitelist only. The whitelist is included in the webhook calls for your convenience: If you added additional data to a datapoint, you can use it here to obtain information for this event. In this example, the custom JSON object that was set for the datapoint

{ 
  "mydeviceid": "afa55e08-ea8c-11e9-86c2-68f728dbd933", 
  "type": "toaster" 
}

The whitelist that is included in the events lets you determine that the device is a toaster and that your custom deviceid is afa55e08-ea8c-11e9-86c2-68f728dbd933. These values are merely meant as an example and don’t make actual sense: You can use whatever data is convenient to you when receiving the webhook call.

Deleting a webhook subscription

With this call, the webhook subscription is deleted:

curl -X DELETE \ 
  https://apim.eu.mybuildings.abb.com/fhapi/v1/events/subscription \ 
  -H 'Ocp-Apim-Subscription-Key: SUBSCRIPTION_KEY' \ 
  -H 'Authorization: Bearer OAUTH2_ACCESS_TOKEN'

After this, you should not longer receive any calls to the webhook. You can activate the subscription again at any time.