Websocket - Trigger

Connect to ws endpoint and trigger flow both on incoming message or websocket opening/closing

Overview

This node connects to a Socket.IO server endpoint and triggers workflows based on WebSocket events such as connection opening, incoming messages, and disconnection. It is useful for real-time applications where you want to react immediately to data pushed from a server via WebSocket, such as chat apps, live notifications, or streaming data updates.

Practical examples include:

Receiving live chat messages and processing them in n8n.
Triggering workflows when a device connects or disconnects from a service.
Handling real-time sensor data streams for monitoring or alerting.

Properties

Name	Meaning
SocketIO URL	The URL of the Socket.IO server to connect to (e.g., `http://localhost:5000`).
Return WS Resource	Whether to return the raw WebSocket resource object with the output. Required if you want to send messages back through the socket. Note: displaying this in execution mode may cause the browser to freeze briefly.
Send Initial Message	Whether to send a message immediately upon connecting to the WebSocket server.
Initial Message	The message content to send right after connecting, required if "Send Initial Message" is enabled.

Output

The node outputs JSON objects representing WebSocket events:

On connection open:

{
  "event": "open",
  "ws": <WebSocket resource or null>
}

On receiving a message:

{
  "event": "message",
  "message": <parsed message content or raw string>,
  "ws": <WebSocket resource or null>
}

On connection close:
```
{
  "event": "close"
}
```

If the "Return WS Resource" option is enabled, the raw WebSocket client instance is included in the output under the ws property, allowing further interaction such as sending messages back.

The node does not output binary data.

Dependencies

Requires a running Socket.IO server to connect to.
Uses the socket.io-client library internally.
No special environment variables are needed, but the user must provide the correct WebSocket URL and optionally an initial message.
No internal credential types are used; authentication must be handled externally if needed by the Socket.IO server.

Troubleshooting

Connection errors: If the node fails to connect, it will throw an error indicating a connection problem. Verify the Socket.IO URL is correct and the server is reachable.
JSON parsing warnings: Incoming messages are attempted to be parsed as JSON. If parsing fails, the raw string is returned and a warning is logged. Ensure the server sends valid JSON if you expect structured data.
Browser freezing: Enabling "Return WS Resource" can cause the browser UI to freeze during execution due to the complexity of serializing the WebSocket object. Disable this option unless you need to send messages back.
Initial message not sent: If "Send Initial Message" is enabled but no message is provided, the node will send an empty string. Make sure to provide a valid message.