WebSocket Trigger

Starts the workflow when a WebSocket message is received

Overview

This node implements a WebSocket Trigger that starts an n8n workflow whenever a WebSocket message is received on a specified port and path. It creates or reuses a WebSocket server to listen for incoming messages, then emits the received data as workflow input.

Common scenarios where this node is useful include:

  • Real-time applications needing to react instantly to WebSocket messages.
  • Integrating with services or devices that push updates via WebSocket.
  • Building event-driven workflows triggered by live data streams.

For example, you could use this node to trigger a workflow when a chat message arrives on a WebSocket server or when IoT sensor data is pushed in real time.

Properties

Name Meaning
Port The TCP port number on which the WebSocket server listens for incoming connections.
Path The URL path segment for the WebSocket server endpoint (e.g., /ws).
Connection ID Optional custom identifier for the WebSocket connection. If empty, the port number is used.
Info Informational notice showing the full WebSocket URL where the server will be available.

Output

The node outputs JSON data representing each received WebSocket message. Each output item includes:

  • All properties of the received message object.
  • Additional metadata fields:
    • serverId: Identifier of the WebSocket server instance.
    • path: The WebSocket server path.
    • port: The port number the server listens on.
    • nodeId: The ID of this node instance.
    • executionId: The current workflow execution ID.
    • clientId: The unique client connection ID sending the message.
    • contextInfo: Contextual information about the server state.

The output is always JSON; no binary data is emitted.

Dependencies

  • Requires a WebSocket server management utility (WebSocketRegistry) bundled with the node.
  • Uses a global execution context to track active servers and executions.
  • No external API keys or credentials are needed.
  • The node must run in an environment where it can open the specified TCP port.

Troubleshooting

  • Port conflicts: If the specified port is already in use by another process, the node may fail to start the WebSocket server. Choose a free port.
  • Server creation errors: Errors during server creation or retrieval will be logged and thrown. Ensure network permissions allow binding to the port.
  • Message handling errors: Exceptions during message processing are caught and logged but do not stop the server.
  • Server verification failure: If the server cannot be verified as running after creation, an error is thrown.
  • Soft close behavior: When the workflow stops, the server is soft-closed to keep existing client connections alive for response nodes. Full closure happens only on workflow deletion or deactivation.

Links and References

Discussion