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

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

Native SDK

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}
```

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.

Message Format

• All SDK → Client messages are JSON strings.

• Messages represent events such as restoreDone, forwardListCompleted, proxyError, portStateUpdate, etc.

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"}

Event Types

restoreDone

Description	Indicates that RestoreData() completed successfully.
Example	{"type":"restoreDone"}

settingPortChange

Description	Emitted when the port range or IP format configuration changes, either automatically or through the HTTP API. On the UI side, the payload should be parsed and the updated port configuration persisted and displayed.
Payload	"60000:20" → start port = 60000, number of ports = 20.
Example	{"type":"settingPortChange", payload: "60000:20"}

forwardListCompleted

Description	Sent when a proxy forwarding operation completes (quick forward, forward by ID, etc.). Useful for signaling the UI to stop loading indicators.
Example	{"type":"forwardListCompleted","payload":"request id"}

proxyError

Description	Emitted when a proxy forwarding operation fails. This applies to all forwarding functions, including CreateWithId, CreateProxyByPortConfigs, QuickCreateProxies, etc. Use this event on the UI side to determine whether the forward operation completed and whether it failed.
Payload	format: <request_id>:<message> <request_id>: ID passed to CreateWithId, CreateProxyByPortConfigs, QuickCreateProxies, etc. <message>: Error details.
Example	{"type":"proxyError","payload":"677e2c4517f247bc89dd66a4:req_proxy_config_error@status:400|message:VALIDATE_FAILED"} {"type":"proxyError","payload":"677e2c4517f247bc89dd66a4:req_proxy_config_error@unknow error"} {"type":"proxyError","payload":"677e2c4517f247bc89dd66a4:req_proxy_config_error@no port available"}

portStateUpdate

Description	Emitted when the state of a port changes. This may occur when: - A port is successfully forwarded and becomes online. - A port goes offline while in use. In response, you can call GetConfigJSON(port) to fetch the latest configuration and status of that port.
Examples	{"type":"portStateUpdate","payload":"60000"}

portRemoved

Description	Sent when a port is automatically removed.
Examples	{"type":"portRemoved","payload":"60000"}

log

Description	Debug log message from the SDK.
Examples	{"type":"log","payload":"debug message"}

httpError

Description	Indicates an error while starting the API server.
Examples	{"type":"httpError","payload":"HTTP Start error"}

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.