> For the complete documentation index, see [llms.txt](https://docs.9proxy.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.9proxy.com/developers/sdk/sdk-websocket-event.md).

# SDK WebSocket Event

The SDK provides an internal WebSocket channel for:

* Receiving runtime notifications (events) from the SDK.
* Monitoring proxy states, port changes, and errors.
* Sending runtime information (internal use).

## How to start the channel

### Node-API SDK

```javascript
sdk.startEventListener(8881, "abcd1234", (data) => {
    console.log("SDK EVENT", data.toString());
});

```

### Native SDK

```c
StartCommunicate(1, 8881, "abcd1234");

```

* endpoint → Port number on which the WebSocket server listens.
* token → Authentication string

## Connection URL

* For Node-API SDK, the client wrapper already establishes the connection and dispatches events to your callback.
* For direct client connections, use:

````
// connection url

```
ws://127.0.0.1:{endpoint}/ws/{token}
```

````

{% hint style="success" %}

## Example

ws\://127.0.0.1:8881/ws/abcd1234

* 127.0.0.1: SDK listens only on localhost.
* {endpoint}: WebSocket server port.
* /ws/: Fixed path.
* {token}: Authentication secret.
  {% endhint %}

## Message Format

* All SDK → Client messages are JSON strings.
* Messages represent events such as restoreDone, forwardListCompleted, proxyError, portStateUpdate, etc.

{% hint style="success" %}

## Example

* {"type":"restoreDone"}
* {"type":"portStateUpdate","payload":"60000"}
* {"type":"forwardListCompleted","payload":"request id"}
* {"type":"proxyError","payload":"1:req\_proxy\_config\_error\@status:400|message:VALIDATE\_FAILED"}

{% endhint %}

## Event Types

### restoreDone

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Indicates that RestoreData() completed successfully.</td></tr><tr><td><strong>Example</strong></td><td>{"type":"restoreDone"}</td></tr></tbody></table>

### settingPortChange

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td><ul><li>Emitted when the port range or IP format configuration changes, either automatically or through the HTTP API.</li><li>On the UI side, the payload should be parsed and the updated port configuration persisted and displayed.</li></ul></td></tr><tr><td><strong>Payload</strong></td><td>"60000:20" → start port = 60000, number of ports = 20.</td></tr><tr><td><strong>Example</strong></td><td>{"type":"settingPortChange", payload: "60000:20"}</td></tr></tbody></table>

### forwardListCompleted

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Sent when a proxy forwarding operation completes (quick forward, forward by ID, etc.).
<br>Useful for signaling the UI to stop loading indicators.</td></tr><tr><td><strong>Example</strong></td><td>{"type":"forwardListCompleted","payload":"request id"}</td></tr></tbody></table>

### proxyError

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td><ul><li>Emitted when a proxy forwarding operation fails.</li><li>This applies to all forwarding functions, including CreateWithId, CreateProxyByPortConfigs, QuickCreateProxies, etc.</li><li>Use this event on the UI side to determine whether the forward operation completed and whether it failed.</li></ul></td></tr><tr><td><strong>Payload</strong></td><td><ul><li>format: &#x3C;request_id>:&#x3C;message></li><li>&#x3C;request_id>: ID passed to CreateWithId, CreateProxyByPortConfigs, QuickCreateProxies, etc.</li><li>&#x3C;message>: Error details.</li></ul></td></tr><tr><td><strong>Example</strong></td><td><ul><li>{"type":"proxyError","payload":"677e2c4517f247bc89dd66a4:req_proxy_config_error@status:400|message:VALIDATE_FAILED"}</li><li>{"type":"proxyError","payload":"677e2c4517f247bc89dd66a4:req_proxy_config_error@unknow error"}</li><li>{"type":"proxyError","payload":"677e2c4517f247bc89dd66a4:req_proxy_config_error@no port available"}</li></ul></td></tr></tbody></table>

### portStateUpdate

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Emitted when the state of a port changes. This may occur when:<br>   - A port is successfully forwarded and becomes online.<br>   - A port goes offline while in use.<br>In response, you can call GetConfigJSON(port) to fetch the latest configuration and status of that port.</td></tr><tr><td><strong>Examples</strong></td><td>{"type":"portStateUpdate","payload":"60000"}</td></tr></tbody></table>

### portRemoved

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Sent when a port is automatically removed.</td></tr><tr><td><strong>Examples</strong></td><td>{"type":"portRemoved","payload":"60000"}</td></tr></tbody></table>

### log

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Debug log message from the SDK.</td></tr><tr><td><strong>Examples</strong></td><td>{"type":"log","payload":"debug message"}</td></tr></tbody></table>

### httpError

<table data-header-hidden><thead><tr><th width="200"></th><th></th></tr></thead><tbody><tr><td><strong>Description</strong></td><td>Indicates an error while starting the API server.</td></tr><tr><td><strong>Examples</strong></td><td>{"type":"httpError","payload":"HTTP Start error"}</td></tr></tbody></table>

## Notes

* The SDK WebSocket server binds only to localhost (127.0.0.1).
* Always generate a random `token` to prevent unauthorized access.
* The token can be refreshed when restarting the SDK.
* Only the last active connection will continue receiving events.