WebSocket Triggers

Orvanta can connect to WebSocket servers and trigger runnables (scripts, flows) when a message is received. Listening happens from servers, so it doesn’t consume workers. WebSocket triggers are not available on the Orvanta Cloud Free and Team plans.

How to use

Create a new trigger on the WebSocket triggers page by specifying the WebSocket server URL. You can use a static URL or specify a script/flow to return the connect URL dynamically, which is useful for passing authentication query parameters. The runnable must return a string.

Once the URL is set, select the runnable to be triggered. The received WebSocket message passes to the runnable as a string argument called msg.

Example script:

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

With a preprocessor:

export async function preprocessor(
  event: {
    kind: "websocket",
    msg: string,
    url: string,
  }
) {
  if (event.kind !== "websocket") {
    throw new Error(`Expected a websocket event`);
  }
  const msg = JSON.parse(event.msg);
  return {
    message_content: msg.content,
    url: event.url
  };
}

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

Send runnable result to WebSocket server

Enable the Send runnable result toggle to send the runnable result back to the WebSocket server upon success (non-null results only). With early return enabled in flows, the chosen node result sends while the rest continues asynchronously.

Enable Send result even on error to forward error results, allowing remote peers to react to failures. When disabled, failed jobs produce no outgoing message.

Initial messages

Specify initial messages to send when connecting to the WebSocket server. These support authentication or subscription messages as static strings or runnables. Static strings use JSON format and stringify before sending. Runnables can return strings or JSON objects, which stringify automatically. Messages send in specified order.

Filters

Restrict which messages trigger the runnable using filters:

• JSON: The message parses as JSON and the filter checks that a specified key exists with a value equal to or a subset of the filter value.

Multiple filters support logic selection:

• AND (default): Message must match all filters.
• OR: Message triggers runnable upon matching any filter.

Application-level heartbeat

Some WebSocket protocols (Discord Gateway, STOMP, custom APIs) require periodic keep-alive messages. Orvanta supports this with configurable heartbeat settings.

Heartbeats send at the Rust level with zero job overhead — no scripts execute.

Configuration

• Interval (seconds): How often to send the heartbeat.
• Message: The message to send. Use {{state}} placeholder for values from incoming messages.
• State field (optional): Top-level JSON field to extract from incoming messages.

Examples

Static heartbeat:

Field	Value
Interval	10
Message	{"type": "ping"}
State field	(empty)

Stateful heartbeat (Discord Gateway):

Field	Value
Interval	41
Message	{"op": 1, "d": {{state}}}
State field	s

Orvanta extracts the s field from Discord events and substitutes it into the heartbeat message automatically.

Error handling

WebSocket triggers support local error handlers that override workspace error handlers for specific triggers.