> For the complete documentation index, see [llms.txt](https://api.developer.homey.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://api.developer.homey.app/http-and-socket.io/socket.io-specification.md).

# Socket.io Specification

Once you've got the [HTTP Specification](/http-and-socket.io/http-specification.md) 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](https://python-socketio.readthedocs.io/en/latest/client.html)
* [Go](https://pkg.go.dev/github.com/zhouhui8915/go-socket.io-client)
* [Rust](https://github.com/1c3t3a/rust-socketio)
* [C#](https://github.com/doghappy/socket.io-client-csharp)

### 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:

```json
{
  "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) { ... })` .

{% hint style="info" %}
To unsubscribe, emit the `unsubscribe` event with `uri` as second parameter.
{% endhint %}

Within the API reference, you can find all events that could be emitted. For example, see [ManagerFlow](https://athombv.github.io/node-homey-api/HomeyAPIV3Local.ManagerFlow.html#section-events).