Triggers

A trigger is the condition that causes a workflow to run. A workflow revision declares one trigger: API, cron, webhook, or event. The current trigger is visible in oxygen workflows get.

Four kinds

Every fire produces a run.

Cron

trigger:
  type: cron
  cron: "0 9 * * 1"
  timezone: "America/New_York"

Use cron triggers for recurring work such as weekly TAM refreshes, daily CRM hygiene, or scheduled enrichment audits.

Cron expressions are standard five-field, so the fastest cadence is once per minute — the scheduler evaluates schedules every minute, and minute-level crons fire reliably. For sub-minute cadence, use a webhook or event trigger (fires per delivery, no cadence floor) or batch the work inside one scheduled run.

Scheduled runs execute on Oxygen's managed workers — nothing runs on your machine, and there is no separate per-run compute fee. Live workflow steps, tool calls, row writes, and retries draw 0.01 credits per action; dry_run and smoke_test cost nothing.

Sizing a 24/7 schedule: once per minute is 43,200 runs per month. A three-step plain workflow meters roughly 3 actions per run — about 130,000 actions, or 1,300 credits, per month. A recipe is different: it bills 1 action per checkpoint its code emits at runtime, so a recipe that loops over 100 items bills 100+ actions per run — 4,320,000+ actions, or 43,200+ credits, per month on the same schedule — and bulk row writes bill 1 action per row. Before committing to a hot schedule, check the observed actions/run on the workflow page or in oxygen workflows get --json (usage.observed) and its 30-day credit projection.

Webhook

trigger:
  type: webhook
  trigger_id: inbound-lead

oxygen workflows get <id> --json returns the webhook URL when the workflow has a webhook trigger. POST a JSON payload; the workflow receives it as input.

Workflow webhooks require an Oxygen secret by default because they can enqueue live workflow runs. Send it in x-oxygen-workflow-secret. Use secret_required: false only for provider callbacks that cannot send custom headers and whose downstream workflow effects are safe to expose publicly.

Event

Two event sources:

trigger:
  type: event
  source: instantly
  event: email.reply_received
  idempotency_key_path: message.id

Enable an integration event before any workflow can subscribe:

oxygen integrations events list --json
oxygen integrations events enable --source instantly --event email.reply_received --json
oxygen integrations events disable --source instantly --event email.reply_received --json
oxygen integrations events deliveries --json

deliveries shows delivery status for provider events, which helps confirm that an external system actually sent the event.

API calls

oxygen workflows call <workflow-id> --input-json '{"id":"123"}' --mode smoke_test --json
oxygen workflows call <workflow-id> --input-json '{"id":"123"}' --mode dry_run --json
oxygen workflows call <workflow-id> --input-json '{"id":"123"}' --mode live --json

call is fire-and-forget: it enqueues the workflow and returns the run id. Use oxygen workflows tail <workflow-run-id> --json to wait for completion.

Emitting events from a workflow

oxygen workflows events emit --source tenant --event lead.qualified --payload-json '{"id":"lead_123","score":87}' --mode dry_run --json

Other workflows subscribed to lead.qualified will fire.

Related

• Workflows — what triggers fire.
• Integrations — provider events that can act as triggers.
• Approvals — even triggered fires require approval before live external writes.