Triggers
API, cron, webhook, and event starts for workflows.
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
| Kind | Fires when |
|---|---|
api | A user or agent calls oxygen workflows call or oxygen_workflows_call |
cron | A cron expression matches the current minute |
webhook | An HTTP POST hits the workflow webhook URL |
event | A subscribed event is emitted (internal or from an integration) |
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.
Webhook
trigger:
type: webhook
trigger_id: inbound-leadoxygen 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:
| Source | Events |
|---|---|
integration | Provider events (e.g. hubspot.contact.created, instantly.reply) |
tenant | Workflow-emitted events (oxygen workflows events emit) |
trigger:
type: event
source: instantly
event: email.reply_received
idempotency_key_path: message.idEnable 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 --jsondeliveries 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 --jsoncall 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 --jsonOther 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.