Write a workflow

Everything comes from one package, @wix/whenever-workflow-sdk, and a workflow module declares three kinds of thing:

manifest

When the workflow runs. Its name, and at least one trigger, each under its own stable key.

export const manifest: WorkflowManifest = {
  name: 'daily-rate-report',
  triggers: [daily({ key: 'morning', at: '09:00', tz: 'Europe/Vilnius' })],
};

defineStep(name, operation)

One named unit of work, recorded on every call. Calls to other services live inside a step.

export const readRate = defineStep('read-rate', async (ctx) => {
  const response = await ctx.integrations.http.get({ url: ctx.config.RATE_URL });
  return response.body;
});

defineWorkflow(run)

The default export: the run function that calls your steps in order, handed a typed context.

export default defineWorkflow<void, { rate: unknown }>(async (ctx) => {
  const rate = await readRate(ctx);
  ctx.log('read rate', { rate });
  return { rate };
});

They are separate so the publish-time extractor can read the manifest without invoking your run function. Triggers are known before a single line of your code has executed, so keep them as literals in the manifest, not something the run function computes.

A manual run carries the trigger the person chose, so a workflow with several triggers can tell every path apart by ctx.trigger.key. A managed event looks like event({ key: 'new-mail', source: 'gmail.new-gmail-message', config: { labels: ['INBOX'] } }), and its source and every config field come from the catalogue.

Unless the helper narrows it, a signed endpoint receives every event kind the sender is configured to send. Branch on ctx.trigger.eventType before any provider write and return an ignored result for the kinds you do not handle — publish refuses a provider write that an unrelated event could reach.

Every http and mcp request names its destination in the source: an origin written as a literal, a whole URL from one ctx.config or ctx.secrets value, or — to answer whoever sent a delivery — the address that delivery carried in ctx.input, in which case the request may carry no workflow secret. An agent loop counts every model turn and every tool call against the run's call budget, so cap the turns and validate each call's arguments before you use them.

Neither class causes a retry, and nothing replays a workflow: a failed step ends its run, and a step is a recorded boundary rather than a resume point. So make a step's work safe to repeat, express the waiting and the duplicate check you need in the workflow itself, and never report an outcome the provider did not confirm.