/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 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) orManualwhen 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), orManual. - 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).
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.
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 noAuthorization 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.
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:
Actions
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 — a404 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: ….
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.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.
Key state to watch
- Health on the roster —
Failing,DegradedandPausedrows rank first. - Paused schedules after a refused fire — a
workflow_trigger_refusedaudit event whose reason beginscreator_authority_lostmeans the creator no longer holdsworkflows:manage. Unsignedon a capability URL — the URL alone starts runs.- A leaked capability URL — rotate its token; pausing does not revoke it.
Related surfaces
- Workflow schedules — create, run, pause and diagnose a schedule.
- Platform Schedules — the admin-only platform-cron console.
- Signed workflow ingress — capability URL status codes, HMAC formats and sender recipes.
- Scheduling and triggers — how schedules and triggers work across Forge.

