WebSocket triggers

Windmill can connect to WebSocket servers and trigger runnables (scripts, flows) when a message is received. Listening is done from the servers, so it doesn't take up any workers. WebSocket triggers are not available on the Cloud.

How to use

Create a new trigger on the WebSocket triggers page. Specify the URL of the WebSocket server. Instead of a static URL, you can also specify a script or flow to return the connect URL. This is useful when you need to pass an authentication query parameter to the connect URL. The runnable must return a string.

Once the URL set, select the runnable that should be triggered by this trigger. The received WebSocket message will be passed to the runnable as a string argument called msg.

Here's an example script:

export async function main(msg: string) {
  // do something with the message
}

And if you use a preprocessor, the script could look like this:

export async function preprocessor(
  msg: string,
  wm_trigger: {
    kind: "websocket",
    websocket: {
      url: string // the WebSocket URL
    }
  },
) {
  // assuming the message is a JSON object
  const msg = JSON.parse(msg); 

  // define args for the main function
  // let's assume we want to use the message content and the url
  return {
    message_content: msg.content,
    url: wm_trigger.websocket.url
  };
}


export async function main(message_content: string, url: string) {
  // do something with the message content and url
}

The trigger also supports additional configuration options:

Send runnable result to WebSocket server

If you enable the "Send runnable result" toggle, the runnable result will be sent to the WebSocket server as a message, as long as the job is a success and the result is not null. Like for sync webhooks, if the flow has the early return setting set, the chosen node result will be sent and the rest of the flow will continue asynchronously.

Initial messages

You can specify a list of initial messages to send to the WebSocket server when connection to the server is established. This is useful for authentication or subscription messages. They can be static strings or runnables that return the message. The static string field is in JSON format and will be stringified before sending. If the JSON value is a string, it will be sent without the wrapping quotes. The runnable can return a string or a JSON object, which will be stringified before sending. The messages are sent in the order they are specified.

Filters

Instead of having all messages trigger the runnable, you can specify filters to only trigger the runnable when the message matches all filters. Windmill supports the following filter:

• JSON: The message is parsed as a JSON object and the filter checks that the filter key exists and the value at the key is equal or is a subset of the filter value.