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 is useful for real-time applications where workflows need to react instantly to incoming WebSocket messages, such as live chat systems, IoT device communication, or real-time notifications.
The node supports different authentication methods (Basic Auth, Header Auth, JWT Auth, or none) to secure the WebSocket connections. It also offers flexible server lifecycle management, allowing multiple workflows to share the same WebSocket server or to have exclusive servers that close when the workflow deactivates.
During manual test executions, it can either auto-stop after receiving the first message or keep listening for multiple messages with an optional timeout.
Practical examples:
- Triggering a workflow when a sensor sends data via WebSocket.
- Starting a workflow upon receiving chat messages in a customer support system.
- Reacting to real-time updates from a third-party service that pushes events over WebSocket.
Properties
| Name | Meaning |
|---|---|
| Port | The TCP port number on which the WebSocket server will listen for incoming connections. Default is 5680. |
| Path | The URL path for the WebSocket server endpoint (e.g., /ws). Only connections targeting this path will be accepted. |
| Connection ID | Optional custom identifier for the WebSocket connection. If not provided, the port number is used as the connection ID. |
| Authentication | Method to authenticate incoming WebSocket connections. Options: - Basic Auth - Header Auth - JWT Auth - None (no authentication) |
| Server Sharing | How the WebSocket server lifecycle is managed when the workflow deactivates: - Shared: Multiple workflows can use the same server instance. - Exclusive: Server closes when this workflow deactivates. |
| Test Execution Behavior | Behavior during manual test runs: - Auto-stop after first message: Stops listening after one message is received. - Keep listening for multiple messages: Continues listening until timeout or manual stop. |
| Test Execution Timeout | Timeout in seconds for manual test executions when "Keep listening" is selected. A value of 0 means no timeout. |
| 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 enriched with metadata:
serverId: Identifier of the WebSocket server instance.path: The WebSocket server path.port: The port number the server listens on.nodeId: The node's unique ID.executionId: The current execution ID.workflowId: The workflow's unique ID.clientId: Unique identifier of the connected client sending the message.serverSharing: Server sharing mode ("shared" or "exclusive").messageCount: Number of messages received during this execution.contextInfo: Additional context about the server state.timestamp: ISO timestamp when the message was received.- Plus all original properties of the incoming WebSocket message.
If the node receives binary data over WebSocket, it would be included in the message payload, but the code does not explicitly handle binary output fields.
Dependencies
- Requires a WebSocket server runtime environment managed by a shared registry singleton.
- Supports authentication requiring credentials configured in n8n for Basic Auth, Header Auth, or JWT Auth.
- No external API dependencies beyond the WebSocket protocol itself.
- Uses global context to manage active servers, listeners, and cleanup tasks.
Troubleshooting
Common issues:
- Port conflicts if multiple nodes try to listen on the same port with exclusive server sharing.
- Authentication failures if credentials are missing or incorrect.
- Workflow edit or deactivation may forcibly close servers unexpectedly if using shared mode.
- Manual test executions may time out or stop listening prematurely depending on configuration.
Error messages:
"Failed to verify server ... is running": Indicates the WebSocket server failed to start or was closed unexpectedly. Check port availability and server sharing settings.- Credential retrieval errors logged during authentication setup suggest misconfigured or missing credentials.
- Cleanup errors during workflow deactivation or manual execution indicate improper server lifecycle handling; ensure correct server sharing mode is selected.
Resolutions:
- Verify port availability and avoid conflicts.
- Ensure proper credentials are set up in n8n for the chosen authentication method.
- Use shared server mode if multiple workflows require the same WebSocket server.
- Adjust test execution behavior and timeout to suit testing needs.