Trigger Overview

Triggers turn external or scheduled occurrences into durable workflow runs. Every trigger starts the same root <steps>, and its normalized input becomes context.payload.

Available triggers

Durable admission

WOML validates and durably admits an occurrence before acknowledging supported external providers. Stable provider identity prevents accidental duplicate runs. Repeating the same identity and payload returns the existing run; reusing an identity with different data is an idempotency conflict.

Multiple triggers

A workflow may declare several triggers, but they all enter the same workflow steps. Inspect context.payload when the trigger type changes the input shape.

Follow one occurrence into a run

When an occurrence arrives, WOML does not immediately execute arbitrary JavaScript. It first validates the provider-specific envelope, normalizes a bounded payload, checks schema and authentication where applicable, assigns or verifies stable occurrence identity, and asks the durable Rust authority to admit the run.

Only after durable admission succeeds does execution begin. This ordering lets webhooks and providers acknowledge work without losing the run between acknowledgement and scheduling.

Design a workflow with multiple triggers

Multiple triggers are useful when different channels should start the same business process:

<triggers>
  <manual id="localTest" />
  <webhook id="apiOrder" path="/webhooks/orders" method="POST" auth="bearer" secret="{{secrets.ORDER_TOKEN}}" />
  <event id="internalOrder" name="order.created" />
</triggers>

All three enter the same <steps>. If their payload shapes differ, normalize them in the first step:

const payload = context.payload;
return {
  orderId: payload.orderId ?? "manual-order",
  source: payload.provider ?? "application"
};

Do not expect each trigger to jump to a different step. Split truly different processes into separate workflows and communicate through calls, starts, or events.

Duplicate occurrence behavior

Providers and HTTP callers may retry delivery. WOML uses stable occurrence identity so a repeated identity with the same payload returns the existing run instead of creating duplicate work. Reusing the same identity with different data is an idempotency conflict because accepting it would make the original event ambiguous.

Trigger deduplication protects run creation. It does not automatically make every API call inside the workflow exactly once; effectful steps still need managed idempotency and careful retry design.

Choose a trigger

Use manual for development and operator initiation, webhook for direct application requests, schedule for calendar time, interval for a fixed elapsed grid, event for one-to-many internal facts, and communication triggers when provider messages are part of the product experience.