Triggers

Start workflows with manual, schedule, poll, and webhook triggers.

A trigger starts or schedules a workflow run. Define triggers with the factories in @lunnoa/toolkit, then register them on createApp({ triggers: [...] }).

Trigger ids must follow <app-id>_trigger_<trigger-name> (for example flow-control_trigger_manually-run).

Trigger factories

Manual trigger example

import {  createManualTrigger,  createTextInputField,} from '@lunnoa/toolkit';export const manuallyRun = createManualTrigger({  id: 'hello_trigger_manually-run',  name: 'Manually run',  description: 'Start the workflow with an optional note.',  inputConfig: [    createTextInputField({      id: 'note',      label: 'Note',    }),  ],  async run({ configValue }) {    return [{ note: configValue.note ?? null, startedAt: new Date().toISOString() }];  },  async mockRun() {    return [{ note: 'example', startedAt: '2026-01-01T00:00:00.000Z' }];  },});

run and mockRun return an array of items. Each item becomes trigger output available to downstream workflow steps.

Webhooks

App-level webhooks often need helpers on createApp:

• verifyWebhookRequest: confirm the request is authentic
• parseWebhookEventType: map the body to an event type your triggers listen for

Use createAppWebhookTrigger when several triggers share one endpoint, or createCustomWebhookTrigger for a dedicated path. Keep verification strict: reject unsigned or unexpected payloads early.

Polling triggers

Poll factories differ mainly in how they detect “new work”:

• Item-based: compare items (ids, cursors, timestamps)
• Length-based: react when a list grows or shrinks
• Time-based: run on an interval regardless of item identity

Store only the cursor or watermark you need; avoid writing large payloads into poll storage.

Next

• Input config: fields on the trigger form
• Actions: steps that run after the trigger fires
• Packaging: register triggers on createApp