Overview
This node implements a WebSocket server trigger that starts an n8n workflow whenever a WebSocket message is received on a specified port and path. It allows workflows to react in real-time to incoming WebSocket messages, making it useful for scenarios such as live data feeds, chat applications, IoT device communication, or any event-driven system where WebSocket is used for messaging.
For example, you could use this node to:
- Trigger a workflow when a sensor sends data via WebSocket.
- Start a workflow upon receiving chat messages from a client.
- React to real-time notifications pushed through a WebSocket connection.
The node supports multiple authentication methods to secure the WebSocket connections, including Basic Auth, Header-based Auth, JWT Auth, or no authentication.
Properties
| Name | Meaning |
|---|---|
| Authentication | The method to authenticate WebSocket connections. Options: Basic Auth, Header Auth, JWT Auth, None |
| Port | The TCP port number on which the WebSocket server will listen for incoming connections |
| Path | The URL path for the WebSocket server endpoint (e.g., /ws) |
| Connection ID | Optional custom identifier for the WebSocket connection. If empty, the port number is used as the ID |
| Info | Informational notice showing the WebSocket server URL based on the configured port and path |
Output
The node outputs JSON data representing each received WebSocket message. Each output item contains:
- The original message payload merged with metadata fields:
serverId: Identifier of the WebSocket server instance handling the message.path: The WebSocket server path.port: The port number the server listens on.nodeId: The ID of the node instance.executionId: The current workflow execution ID.clientId: Identifier of the WebSocket client that sent the message.contextInfo: Additional context about the server state.
The output is always JSON; there is no binary data output.
Dependencies
- Requires a WebSocket server registry singleton to manage server instances and listeners.
- Supports optional authentication credentials which must be configured in n8n:
- Basic Auth credential for Basic Authentication.
- Header Auth credential for header-based authentication.
- JWT Auth credential for JWT token authentication.
- No external environment variables are explicitly required beyond standard credential setup.
Troubleshooting
- Common issues:
- Port conflicts if another service is already using the specified port.
- Authentication failures if credentials are missing or incorrect.
- Workflow edit mode may cause the WebSocket server to close and restart, potentially interrupting active connections.
- Error messages:
"Failed to verify server ... is running"indicates the WebSocket server failed to start properly.- Credential loading errors if the selected authentication method's credentials are not set up correctly.
- Resolutions:
- Ensure the chosen port is free and accessible.
- Verify that the correct credentials are configured in n8n for the selected authentication method.
- Avoid editing the workflow while expecting persistent WebSocket connections, or handle reconnections gracefully.