Websocket Trigger

Basic Websockets Node using "ws" library
Join our community

Overview

This node acts as a WebSocket client that connects to a specified WebSocket server URL and listens for incoming messages. It is designed as a trigger node, meaning it activates workflows when new data arrives through the WebSocket connection.

Common scenarios where this node is beneficial include:

  • Real-time data streaming applications, such as live chat messages, notifications, or sensor data.
  • Integrating with services that push updates via WebSockets instead of traditional HTTP requests.
  • Building event-driven workflows that react immediately to external events without polling.

For example, you could use this node to connect to a cryptocurrency exchange's WebSocket feed to receive live price updates and trigger downstream processing or alerts.

Properties

Name Meaning
Websocket URL The URL of the WebSocket server to connect to (e.g., ws://example.com/). This specifies the endpoint where the node will establish the WebSocket connection.

Output

The node outputs data whenever a message is received from the WebSocket server. The output structure is:

  • json: An array containing one object per message.
    • If the incoming message is valid JSON, it is parsed and returned as a JavaScript object.
    • If parsing fails, the raw message string is returned.

No binary data output is produced by this node.

Example output JSON:

[
  {
    "someKey": "someValue",
    "anotherKey": 123
  }
]

or if the message is not JSON-parsable:

[
  "raw message string"
]

Dependencies

  • Requires the ws library for WebSocket client functionality.
  • No special environment variables are needed beyond providing a valid WebSocket URL.
  • The node expects an active internet/network connection to reach the specified WebSocket server.

Troubleshooting

  • Connection errors: If the WebSocket URL is invalid or the server is unreachable, the node will throw a connection error with a message like "WebSocket connection error". Verify the URL and network connectivity.
  • Message parsing warnings: If incoming messages are not valid JSON, a warning is logged but the raw message is still emitted. Ensure the server sends JSON-formatted messages if your workflow depends on structured data.
  • Unexpected disconnections: The node does not explicitly handle reconnection logic. If the connection drops, the workflow may stop receiving messages until manually restarted.

Links and References

Discussion