Websockets Node

Websockets Node
Join our community

Overview

This node establishes a WebSocket connection to a specified server URL and listens for incoming messages. It can send an initial message upon connection, maintain the connection with periodic heartbeat (ping) messages, and automatically attempt to reconnect if the connection closes unexpectedly. The node outputs received WebSocket events and data in configurable formats.

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 that require authentication tokens or initialization messages.
  • Monitoring WebSocket server status and reacting to open, message, error, and close events.

Practical example:

  • Connect to a cryptocurrency exchange's WebSocket feed to receive live trade data, parse JSON messages, and trigger workflows based on specific trading signals.

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 when establishing the WebSocket connection. Can add multiple name-value pairs.
Return Data Type Format of the returned data: String (raw text), Json (parsed JSON object), or Binary (binary data).
Init Send Data Initial message sent immediately after the WebSocket connection opens (e.g., authentication token). If empty, no message is sent.
Ping Data Heartbeat message sent periodically to keep the connection alive. If empty, no heartbeat is sent.
Ping Timer(s) Interval in seconds between sending heartbeat messages. Only used if Ping Data is set.
ReConnect Times Maximum number of automatic reconnection attempts if the WebSocket connection closes unexpectedly.

Output

The node emits output items representing WebSocket events with the following structure in the json field:

  • event: A string indicating the event type, one of "open", "message", "error", or "close".
  • ws: The WebSocket client instance (internal use, typically not needed downstream).
  • data: For "message" events, contains the received data formatted according to the selected Return Data Type:
    • If string, raw text message.
    • If json, parsed JSON object.
    • If binary, binary data prepared for n8n binary handling.
  • code: For "close" events, the WebSocket close code.

If the Return Data Type is set to binary, the node prepares the received data as binary content suitable for further binary processing in n8n.

Dependencies

  • Requires a WebSocket server accessible at the provided URL.
  • Optionally uses an API key credential or cookie for authentication, which can be added as a header named Cookie.
  • Uses the ws npm package internally to manage WebSocket connections.
  • No additional environment variables are required.

Troubleshooting

  • Missing WebSocket URL: The node will throw an error if the WebSocket URL is not configured.
  • Connection errors: Errors during connection emit an error event and may cause the node to stop unless reconnection attempts remain.
  • Reconnection limits: If the maximum reconnection attempts are reached, the node stops trying to reconnect.
  • Invalid JSON messages: If Return Data Type is set to JSON but the incoming message is not valid JSON, parsing will fail and may cause errors.
  • Heartbeat not working: Ensure both Ping Data and Ping Timer are set; otherwise, no heartbeat messages will be sent.
  • Initial message not sent: If Init Send Data is empty, no initial message is sent after connection.

To resolve common issues:

  • Verify the WebSocket URL and headers are correct.
  • Check network connectivity and server availability.
  • Adjust reconnection attempts and heartbeat settings as needed.
  • Validate the format of incoming messages matches the expected Return Data Type.

Links and References

Discussion