> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gloo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workflow triggers

> Start a workflow on a schedule or from an outside system: the Schedules roster, a workflow’s Schedule tab, when a scheduled run fires, and the capability URL card.

A workflow starts from a person, a schedule or an outside system. The **Schedules** roster (`/production/workflows/convex/schedules`) lists every in-scope workflow with its cadence, and each workflow's **Schedule** tab manages both of its triggers: the clock and a capability URL that an outside system POSTs to. Neither needs admin access. [Workflow schedules](https://docs.gloo.com/forge/console/production/workflow-schedules.md) walks through creating and diagnosing a schedule step by step.

## What you can do

* See every in-scope workflow, scheduled or manual, on the **Schedules** roster, and run, schedule, edit, pause or unschedule it.
* Create a recurring or one-shot schedule from a workflow's **Schedule** tab, with its run parameters.
* Create a capability URL, edit its input mode, verification, idempotency and rate limit, pause it, or rotate its token.
* Read the last 20 requests a capability URL received, with the reason each was rejected.

## Scheduling workflows

Scheduling is workflow-centric and lives here in **Workflows** — you don't need admin access. `/platform/schedules` is the admin-only platform-cron ops console; non-admins are redirected here.

**The Schedules roster** (the **Schedules** tab) lists **every** in-scope workflow — scheduled *and* manual — one row each:

* **Schedule** — the cadence chip (e.g. `Daily 09:00`) or `Manual` when the workflow has no trigger.
* **Next fire** — relative time (absolute on hover), or `—` for manual / paused.
* **Health** — derived from the workflow's recent run outcomes: `Healthy`, `Degraded` (a failure among the last 5 settled runs), `Failing` (most recent settled run failed), `Paused`, `Warming up` (no settled runs yet), or `Manual`.
* **Recent** — a sparkline of the last run outcomes.
* **Cost** — the last run's cost and token count.
* **Actions** — **Run now** (fires the workflow immediately and jumps to the new run). Scheduled rows also offer **Edit**, **Pause** / **Resume**, and **Unschedule** (removes the schedule — the workflow returns to manual, and **Run now** / **Schedule…** come back). Manual rows offer **Schedule…**. A one-shot whose fire time has already passed shows **Expired** and can only be un-scheduled (not resumed — create a new one).

The `All / Scheduled / Manual` filter and name search narrow the list; rows are ranked attention-first (failing → degraded → paused, then healthy, then manual). Clicking a row opens a drawer with that workflow's recent runs.

**The per-workflow Schedule tab** (workflow detail → **Schedule**, `?tab=schedule`) manages one workflow's schedule:

* If the workflow is scheduled, it shows the current trigger with **Edit**, **Pause / Resume**, and **Delete**, plus a missed-windows drawer when the trigger has fallen behind.
* If it's manual, a **Schedule this workflow** button opens the create dialog pre-scoped to this workflow.
* Creating a **recurring** schedule uses a friendly recurrence builder — choose **every N minutes/hours**, **daily**, **weekly** (on selected days), or **monthly** at a time and the cron is generated for you. An **Advanced (cron)** toggle exposes the raw expression, and editing a hand-written cron opens in Advanced automatically so it's never misrepresented. **One-shot** schedules use a date/time picker.
* Below, its **run history** defaults to scheduled runs with an **All runs** toggle.

**When a fire happens.** Each minute the scheduler claims every due schedule; the claim is the fire. A schedule that follows the active version runs the version that is active when the scheduler claims the fire, even if a newer version is published before the run starts. A pause or delete that commits before a claimed scheduled fire launches cancels that fire and records why (a `workflow_trigger_fire_skipped` audit event); a one-shot is consumed when it is claimed, so pausing it afterwards does not stop that fire; a fire that already launched is a run — cancel it from the run (or with `runs:manage` over the API).

**A schedule stops when its creator loses authority.** Before every fire the scheduler checks that the person who created the schedule still holds `workflows:manage` at both org units the schedule was created against: the workflow's home and the schedule's own org unit, the unit its runs are recorded in, which decides who can read them (a grant at the unit, at one of its ancestors, or at the platform covers it). If they do not — the role was removed or now covers only another unit, their worker seat or person was deactivated, or the creator cannot be found or is not a person — the fire launches nothing and the schedule is paused, with a `workflow_trigger_refused` audit event whose reason begins `creator_authority_lost` (`creator_authority_lost: trigger org unit (<unit id>): …` when only the schedule's own org unit was lost). A schedule whose workflow was deleted is paused the same way after one refused fire (reason `creator_authority_lost: the workflow no longer exists (workflow-missing)`). Resuming does not change the creator, so the next fire pauses it again; to keep the schedule running, delete it and create it again as someone who holds `workflows:manage` at both. If the check cannot be decided (an existing workflow's home org unit is missing or cannot be resolved, the schedule's own org unit cannot be resolved and the creator holds no platform grant, the creator's role grants are too many to read in full, or their person record's merge history is corrupt), that fire is refused and recorded with reason `creator_authority_indeterminate`, and the schedule keeps running.

The create/edit dialog reads the selected workflow's input contract and presents it by role, the same way the launch dialog does. **Run parameters** are editable and stored as that trigger's own dispatch arguments, validated against the version the trigger fires. **Derived inputs** are shown read-only — they are computed at fire time and cannot be pinned on a trigger, so the dialog never offers them. **Assets** are bound at the workflow level rather than per trigger, so they do not appear here at all; manage them from the workflow itself.

Leave a run parameter blank and the run falls back to that input's default at fire time — which is what makes a `defaultExpr` such as `previousMonth(today())` the usual way to schedule a periodic workflow with nothing stored on the trigger at all.

## Capability URL (ingress trigger)

The **Schedule** tab answers "how does this workflow get fired?", so both kinds of trigger live there: the clock above, and a **Capability URL** card below it. A capability URL is a secret web address an outside system POSTs to in order to start a run of this workflow. There is no `Authorization` header — **the URL itself is the credential**. It exists for senders that cannot hold an OAuth token: GitHub, Linear, Zapier, vendor "notify this URL" fields.

Creating, editing, pausing, and rotating all require `workflows:manage`. Reading the request log requires `workflows:read`.

> [!WARNING]
>
> The full URL is shown **exactly once**, at create and at rotate. Forge stores only a hash of the token and cannot show it again. A capability URL that leaks into a log, a screenshot, or a chat paste is a compromised trigger — **Rotate token** is the only revocation. Pausing is not revocation.

### The card

Before a trigger exists the card shows **No capability URL** with a **Create ingress trigger** button. Once configured it shows a status badge (`Active` / `Paused`), the token prefix (`wht_` plus the first 8 characters — enough to tell two triggers apart, not enough to guess the rest), and four fields:

| Field | What it tells you |
| - | - |
| **Input mode** | `workflow schema` — the sender's body must satisfy the workflow's declared inputs. Or `wrapped under <key>` — the whole body is handed to the workflow under that one key. Use `wrap` for third-party payloads whose shape is not yours. |
| **Verification** | `HMAC-SHA256 via <header>`, or **`Unsigned`** in amber. Unsigned means the URL alone starts runs. |
| **Idempotency** | The header name used as a dedupe key, or `Off`. A repeated value within 24h returns the original run id and starts nothing new. |
| **Rate limit** | Requests per minute. Default 60, configurable 1–600, with bursts of up to 10. |

### Actions

| Action | Effect |
| - | - |
| **Edit config** | Change input mode, wrap key, verification, idempotency header, or rate limit. The URL is unchanged. |
| **Pause** / **Resume** | Paused requests are answered `410 Gone`. **The token is unchanged**, so resuming restores the same URL. Use for maintenance windows, never for a suspected leak. |
| **Rotate token** | Mints a new URL and kills the old one **immediately** — no grace window, no overlap. Update the sender first, or expect a gap. |

### Recent requests

Below the card is the last 20 requests this trigger received, retained 7 days. This is **where the real rejection reasons live**. The endpoint deliberately tells senders nothing beyond a status code — a `404` reads identically whether the token is malformed, unknown, or the workflow is gone — because anyone on the internet can probe it. The invocation row carries the reason an operator needs: `signature verification failed`, `per-minute rate budget exhausted`, `input validation failed: …`.

> [!NOTE]
>
> Two rejection classes never appear here, because no trigger matched them: a `404` where the token resolved to nothing at all, and an oversized or unreadable body settled before the database was touched. An empty list alongside a sender reporting `404` means the token is wrong, not the configuration.

Runs started this way are stamped with source `webhook` and carry the trigger id, so every run is traceable back to the URL that fired it. The full contract — status-code table, HMAC formats, and worked GitHub / Linear / Zapier recipes — is in [Signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md).

## Key state to watch

* **Health** on the roster — `Failing`, `Degraded` and `Paused` rows rank first.
* **Paused schedules after a refused fire** — a `workflow_trigger_refused` audit event whose reason begins `creator_authority_lost` means the creator no longer holds `workflows:manage`.
* **`Unsigned`** on a capability URL — the URL alone starts runs.
* **A leaked capability URL** — rotate its token; pausing does not revoke it.

## Related surfaces

* [Workflow schedules](https://docs.gloo.com/forge/console/production/workflow-schedules.md) — create, run, pause and diagnose a schedule.
* [Platform Schedules](https://docs.gloo.com/forge/console/platform/schedules.md) — the admin-only platform-cron console.
* [Signed workflow ingress](https://docs.gloo.com/forge/run/ingress.md) — capability URL status codes, HMAC formats and sender recipes.
* [Scheduling and triggers](https://docs.gloo.com/forge/run/scheduling-and-triggers.md) — how schedules and triggers work across Forge.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.