Websocket - TriggerInstall

Overview

This node connects to a specified WebSocket server URL and triggers the workflow based on WebSocket events such as connection opening, incoming messages, and connection closing. It is useful for real-time data processing scenarios where you want your workflow to react immediately to live updates or events pushed from a WebSocket server.

Common use cases include:

• Receiving live notifications or updates from a WebSocket API.
• Reacting to streaming data feeds (e.g., stock prices, chat messages).
• Maintaining a persistent connection to a service that pushes events.

For example, you can connect to a WebSocket endpoint of a chat service and trigger workflows whenever a new message arrives or when the connection status changes.

Properties

Output

The node outputs JSON objects representing WebSocket events with the following structure:

• event: The type of event, one of "open", "message", or "close".
• message: Present only for "message" events; contains the parsed message received from the WebSocket server. If parsing fails, the raw string is provided.
• ws: Present if "Return WS Resource" is enabled; contains the WebSocket connection object allowing further interaction (e.g., sending messages).

Example output JSON for a message event:

{
  "event": "message",
  "message": {
    /* parsed message content */
  },
  "ws": { /* WebSocket resource object, if returned */ }
}

If binary data were supported, it would be indicated here, but this node handles text-based WebSocket messages only.

Dependencies

• Requires the ws library for WebSocket client functionality.
• Needs an active internet connection to reach the specified WebSocket URL.
• No special environment variables are required beyond standard n8n credentials for authentication if the WebSocket server requires it (not handled internally by this node).

Troubleshooting

• Connection errors: If the WebSocket URL is incorrect or the server is unreachable, the node will throw a connection error. Verify the URL and network connectivity.
• JSON parse warnings: Incoming messages are attempted to be parsed as JSON. If parsing fails, the raw message string is used instead. Ensure the server sends valid JSON if you rely on structured data.
• Browser freeze warning: Enabling "Return WS Resource" may cause the browser UI to freeze briefly during execution because the WebSocket object is large and complex. Use this option only if you need to send messages back through the connection.
• Initial message not sent: If "Send Initial Message" is enabled but no message is provided, the node defaults to sending an empty JSON object ({}).

Links and References

• WebSocket API MDN Documentation
• ws npm package - WebSocket client library used internally by the node