WebSocket Trigger icon

WebSocket Trigger

Starts a WebSocket server with bidirectional communication and triggers workflow on incoming connections/messages
Join our community

Overview

This node implements a WebSocket server trigger for n8n workflows. It listens on a specified port and path, accepting WebSocket connections from clients. The node can trigger workflows on client connections, incoming messages, or both. It supports bidirectional communication, allowing responses to be sent back to clients, including echoing messages or sending custom responses. It also supports automatic welcome messages, periodic server messages, and auto-replies after receiving messages. Authentication can be enforced via header tokens or query parameters. Advanced options include connection limits, ping intervals, JSON message parsing, message size limits, and connection cleanup intervals. This node is useful for real-time applications requiring WebSocket communication, such as chat servers, live notifications, or interactive dashboards.

Use Case Examples

  1. Trigger workflow when a client connects to the WebSocket server to log connection metadata.
  2. Trigger workflow on incoming messages to process and respond to client data in real-time.
  3. Send automatic welcome messages to clients upon connection and periodic heartbeat messages to all connected clients.
  4. Enforce token-based authentication for WebSocket connections to secure access.

Properties

Name Meaning
Port Port number for the WebSocket server to listen on (accessible from 0.0.0.0)
Path Path for WebSocket connections (e.g., /websocket)
Bind Address Network interface to bind the WebSocket server to
Trigger On When to trigger the workflow
Response Mode How to respond to incoming messages
Custom Response Custom response to send back to client (used if Response Mode is Custom)
Auto Messages Settings for automatic messages such as welcome, periodic, and auto-reply messages
Authentication Authentication method for WebSocket connections
Token Header Name Header name for authentication token (used if Authentication is Header Token)
Token Parameter Name Query parameter name for authentication token (used if Authentication is Query Parameter)
Expected Token The expected token value for authentication
Advanced Options Advanced configuration options for the WebSocket server

Output

JSON

  • event - Type of event triggering the workflow (connection or message)
  • data - Data received from the client (message content or null for connection event)
  • connectionInfo - Metadata about the WebSocket connection (e.g., remote address, port, user agent, origin, timestamp, connection ID)
  • meta
    • totalConnections - Total number of active WebSocket connections
    • serverInfo
      * host - Host address the WebSocket server is bound to
      * port - Port number the WebSocket server is listening on
      * path - Path for WebSocket connections
    • messageSize - Size of the incoming message in bytes (for message events)
    • timestamp - Timestamp of the event

Dependencies

  • ws (WebSocket library)

Troubleshooting

  • Ensure the specified port is not already in use by another application to avoid server startup errors.
  • If authentication is enabled, verify that the token header or query parameter matches the expected token to allow connections.
  • Check network firewall settings to ensure the bind address and port are accessible as intended (e.g., external access vs localhost only).
  • If JSON parsing is enabled, malformed JSON messages may cause parsing errors; ensure clients send valid JSON if this option is used.
  • Monitor the maximum connections setting to avoid rejecting new clients when the limit is reached.
  • If periodic or auto-reply messages are not sent, verify the corresponding settings and intervals are correctly configured.

Links

Discussion