NATS Triggers

Orvanta can connect to NATS servers and trigger runnables (scripts, flows) when a message is received. The trigger listens on the API server rather than on a worker, so an idle NATS trigger doesn’t tie up worker capacity. This functionality is a self-hosted Enterprise feature.

How to use

Core NATS

Create a new trigger from the NATS triggers page. Configure a NATS connection with server hostnames in hostname[:port] format (no nats:// prefix) and the required authentication. Then specify the subject to listen on — wildcards are supported, but Core NATS only lets you configure a single subject per trigger.

Finally, select the script or flow to run. The message payload is base64-encoded and passed to the runnable as a string argument named payload.

Sample script implementation:

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

With a preprocessor, the script structure becomes:

export async function preprocessor(
  event: {
    kind: "nats",
    payload: string, // base64 encoded payload
    servers: string[];
    subject: string; // the specific subject the message was received from
    length: number;
    headers?: Record<string, string[]>;
    status?: number;
    description?: string;
  }
) {
  if (event.kind !== "nats") {
    throw new Error(`Expected a nats event`);
  }
  // assuming the message is a JSON object
  const msg = JSON.parse(atob(event.payload));

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

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

JetStream

JetStream adds persistence and lets a single trigger listen on more than one subject at a time. Because messages are persisted, a trigger that reconnects after a temporary outage still receives what it missed instead of dropping it.

If the stream you name doesn’t exist yet, Orvanta creates it. If it does exist, Orvanta updates it to include the subjects you configured while leaving the rest of its settings alone — subjects already on the stream are not removed just because a trigger stops referencing them.

Orvanta creates a durable push consumer using the trigger’s name and configured subjects, replacing any consumer that already exists under that name. The consumer name doubles as the DeliverSubject, so it must be unique per NATS account.

Error handling

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