SQS Triggers

Orvanta can connect to an SQS queue and trigger a script or flow in response to messages received. It authenticates with an AWS or AWS OIDC resource and takes a queue URL plus an optional selection of message-attribute names to fetch (all attributes when none are selected).

SQS triggers are an Enterprise-tier feature (sqs_trigger in the edition matrix) and are compiled into the single Orvanta enterprise build. Creating or updating one on a lower licence tier is refused.

Delivery is at-least-once. Orvanta deletes a message only after the job has been dispatched; if dispatch fails, the message is made visible again immediately, so the same message_id can arrive more than once. Dead-letter behaviour is whatever redrive policy you configured on the queue.

Preprocessor event shape

An SQS-triggered preprocessor receives an event shaped like this (the shape is built from the trigger’s job arguments in the platform code):

export async function preprocessor(
  event: {
    kind: "sqs",
    body: string | null,
    message_id: string,
    attributes: Record<string, string>,
    approximate_receive_count: number | null,
    sent_timestamp: number | null // epoch milliseconds
  }
) {
  if (event.kind !== "sqs") {
    throw new Error(`Expected a SQS event`);
  }
  // assuming the message body is a JSON object
  const data = JSON.parse(event.body ?? "{}");

  return {
      content: data.content,
      metadata: {
          sentAt: event.sent_timestamp,
          messageId: event.message_id
      }
  };
}

• body: The message body. SQS bodies are always UTF-8 text, so it is passed as-is rather than base64-encoded.
• message_id: A unique identifier assigned to each message by SQS. SQS is at-least-once, so the same message_id can arrive more than once.
• attributes: User-defined string message attributes. The trigger’s message_attributes setting selects which attribute names are fetched (all of them when unset). Binary and number attribute types are not requested.
• approximate_receive_count: SQS’s ApproximateReceiveCount; it climbs past 1 on redelivery.
• sent_timestamp: When the message was sent, in epoch milliseconds.

The queue URL and the receipt handle are not part of the event.

See Preprocessors for how a preprocessor’s return value maps onto a script’s main() parameters.