Triggers

A workflow declares at least one trigger on meta.triggers. Triggers only start runs; once running, every run behaves the same regardless of what started it.

Cron

triggers: [
  {
    kind: "cron",
    expr: "0 9 * * 1-5",
    timezone: "America/New_York",
    input: { mode: "full" }, // optional: the payload every scheduled run fires with
  },
],

expr takes standard 5-field cron (or 6 fields with seconds). timezone is optional and defaults to UTC; daylight saving is handled for you. A workflow may declare several cron triggers.

input is optional and pins a static payload for every run this schedule fires, readable in the program as the input binding and matched against the workflow's input_schema when one is declared. Omit it and scheduled runs fire with no input. For a payload or cadence you compute at runtime, use workflows.schedule() instead of a static cron trigger.

Webhook

triggers: [
  { kind: "webhook", auth: "token" },
],

Deploying a webhook-triggered workflow provisions an inbound URL, shown in the dashboard. The request body becomes the run's input. auth picks how callers prove themselves:

• token: the secret is part of the URL path (/v1/workflows/<id>/<token>). Paste that one URL into any app that sends webhooks (Linear, GitHub, Stripe); there is no header to set and no separate secret to copy. The full URL is shown once when you generate it, so save it then.
• signature: the caller signs the raw request body with HMAC-SHA256 and sends it as X-Boardwalk-Signature: sha256=<hex>. Use this when you control the sender and want the payload cryptographically verified.

Either way the URL is unguessable and the secret is regenerable from the dashboard. Treat a token URL like a password: anyone who has it can start a run.

Manual

triggers: [{ kind: "manual" }],

Run it on demand: the Run button in the dashboard, boardwalk run from the CLI, or another workflow via workflows.call(). Workflow-to-workflow calls are manual triggers under the hood; the parent run is recorded on the child.

On another workflow

triggers: [
  { kind: "workflow_run", workflows: ["ci"], conclusions: ["success"] },
],

A workflow_run trigger fires this workflow whenever a named upstream workflow in the same org finishes. List one or more upstream slugs in workflows, and optionally filter by outcome with conclusions (success, failure, or cancelled; omit it to fire on any). The upstream run's result becomes this run's input, so you can chain workflows without wiring a webhook between them. Available on the hosted platform and a self-hosted server.

Reading the trigger payload

import { input } from "@boardwalk-labs/workflow";

// input is a value, not a function: the webhook body, run() --input, call() input,
// or a cron trigger's declared input.
console.log(input);

Whatever started the run, its payload is available to the program as the input binding (a value, not a function call). Locally, pass one with boardwalk dev . --input '{...}'.

A run can also name the environment it executes in, which selects its secrets and variables. You pass it when the run starts (from the dashboard, boardwalk run --environment, the REST trigger, or workflows.call()), and a schedule pins one for every run it fires. Omit it and the run uses the organization base.