Overview
This node establishes a WebSocket connection to a specified server URL and listens for incoming messages. It is designed as a trigger node, meaning it activates workflows when WebSocket events occur. The node supports sending an initial message upon connection, periodic heartbeat (ping) messages to keep the connection alive, and automatic reconnection attempts if the connection closes unexpectedly.
Common scenarios where this node is beneficial include:
- Real-time data streaming from WebSocket APIs (e.g., live financial data, chat messages, IoT device updates).
- Maintaining persistent connections with services that push event notifications.
- Integrating with custom WebSocket servers for real-time workflow triggers.
Practical example:
- Connecting to a cryptocurrency exchange's WebSocket feed to receive live trade data and trigger downstream processing or alerts in n8n.
- Listening to a chat server's WebSocket to automate responses or log messages.
Properties
| Name | Meaning |
|---|---|
| Websocket URL | The URL of the WebSocket server to connect to (e.g., ws://example.com/my-namespace). |
| Websocket Headers | Optional HTTP headers to include during the WebSocket handshake, specified as multiple name-value pairs. |
| Return Data Type | Format of the received data: string, json (parsed JSON), or binary (raw binary data). |
| Init Send Data | Initial message sent immediately after the WebSocket connection opens (e.g., authentication token). |
| Ping Data | Heartbeat message sent periodically to keep the connection alive; if empty, no heartbeat is sent. |
| Ping Timer(s) | Interval in seconds between heartbeat messages. |
| ReConnect Times | Maximum number of automatic reconnection attempts if the connection closes unexpectedly. |
Output
The node outputs JSON objects representing WebSocket events. Each emitted item contains:
event: The type of WebSocket event ("open","message", or"close").ws: The WebSocket instance (internal reference, mainly for internal use).data: For"message"events, the content received from the WebSocket server, formatted according to the selected "Return Data Type":- If
string, raw text. - If
json, parsed JSON object. - If
binary, binary data prepared for further processing.
- If
code: For"close"events, the close code indicating why the connection closed.
If the "Return Data Type" is set to binary, the node prepares the received data as binary output suitable for workflows expecting binary input.
Dependencies
- Requires the
wslibrary for WebSocket client functionality. - No external API keys or credentials are inherently required by the node itself, but connecting to some WebSocket servers may require authentication tokens or headers configured via the "Init Send Data" or "Websocket Headers" properties.
- No special environment variables or n8n configurations are needed beyond standard node setup.
Troubleshooting
- Missing WebSocket URL: The node throws an error if the WebSocket URL is not configured. Ensure the "Websocket URL" property is set correctly.
- Connection errors: Errors during connection emit error events logged to the console and passed to the workflow. Check network connectivity and server availability.
- JSON parsing errors: If "Return Data Type" is set to
jsonbut the incoming message is not valid JSON, the node will throw a parsing error. Usestringreturn type if unsure about message format. - Heartbeat not working: If "Ping Data" is empty, no heartbeat messages are sent, which might cause some servers to close the connection due to inactivity.
- Reconnection limits: The node attempts to reconnect up to the configured "ReConnect Times". If the connection repeatedly fails, consider increasing this value or investigating server stability.