Socket.io Specification

Once you've got the HTTP Specification set up, you might be interested in receiving realtime events from Homey. For example, to do something when a device turns on.

While Socket.io is primarily developed for Node.js, there are many alternative clients available for other languages. Here are a few examples.

• Python

• Go

• Rust

• C#

Step 1 — Connect to Socket.io

Connect to the localUrl, localUrlSecure or remoteUrl of Homey Pro or Homey Cloud with only the websocket transport. We recommend using a pingTimeout of 8000ms and pingInterval of 5000ms.

Step 2 — Authenticate with Homey

Emit an event handshakeClient with the following object as parameter:

{
  "token": "<session token>", // The Session Token
  "homeyId": "abc..." // The ID of the Homey
}

As third and last parameter, provide a callback function with a two parameters (error, result) . If error is present, it could be a string with an error message or an object with the error and error_description properties.

If result is set, authentication was successful. Within result, there is a property called namespace , for example /api. This is the root namespace for Socket.io where broadcasts happen. Your client should again connect to this namespace.

Step 3 — Subscribe to Events

To subscribe to realtime events, you need to let Homey know you are interested in these events. To do so, emit a subscribe event with an uri as second parameter. As third parameter, provide a callback method with an (error, result) pattern.

An URI could be, for example, homey:manager:flow to get events when a Flow gets created, updated and deleted. Another example is homey:device:abc... to get capability updates of a specific device.

After subscribing, bind a local event listener where the event name is the uri. For example, in JavaScript, this looks like socket.on(uri, (event, data) { ... }) .

To unsubscribe, emit the unsubscribe event with uri as second parameter.

Within the API reference, you can find all events that could be emitted. For example, see ManagerFlow.