Skip to main content
View as Markdown

Automation Triggers

A trigger is the single event that starts an automation. Sovrium ships 9 trigger types. Every automation declares exactly one trigger object whose type selects the variant; the remaining properties configure it.

automations:
  - name: order-webhook
    trigger:
      type: webhook
      method: POST
    actions:
      - { name: ack, type: webhook, operator: response, props: { status: 202 } }

Trigger Catalog

type Fires when… Key context exposed
webhook An inbound HTTP request hits the automation's endpoint. {{trigger.body}}, headers, query
cron A cron schedule elapses. scheduled time
record A record is created, updated, or deleted in a watched table. {{trigger.data.*}} (the row)
auth An authentication event occurs (sign-up, sign-in, …). the auth event + user
form A top-level form is submitted. {{trigger.data.*}} (form values)
manual An admin clicks a button or calls the trigger API. {{trigger.inputData.*}}
automation-call Another automation invokes this one via the automation/call action. {{trigger.inputData.*}}
automation-failure A watched automation fails. the failed run + error
comment A comment is created on a record. $trigger.comment.*, $trigger.record.*

Webhook Trigger

Exposes an HTTP endpoint that, when hit, starts the automation. Accepts one or more methods and supports inbound authentication, custom responses, request/query validation, rate limiting, and deduplication.

Property Description
method HTTP method(s) to accept — GET/POST/PUT/PATCH/DELETE, or an array of them. Required.
secret Secret for HMAC signature verification (e.g. $env.WEBHOOK_SECRET).
respondImmediately When true (default), respond 202 immediately; when false, wait for the run to complete.
auth Inbound auth config — type is bearer, apiKey, hmac, or basic (see table below).
response Custom response: statusCode/status, body (string template or JSON), headers.
requestSchema JSON Schema validating the request body.
querySchema JSON Schema validating query parameters.
rateLimit { maxRequests, windowSeconds } rate-limit config for the endpoint.
deduplicationKey Template computing a dedup key (e.g. "{{body.orderId}}") — repeated keys within the window are dropped.
deduplicationWindow Dedup window in seconds (default 300).

Inbound auth.type options: bearer (with token, prefix), apiKey (with key, header), hmac (with secret, algorithm), basic (with username, password). All credential values support $env.VAR.

trigger:
  type: webhook
  method: [POST]
  auth: { type: hmac, secret: $env.STRIPE_SIGNING_SECRET, algorithm: sha256 }
  deduplicationKey: '{{body.id}}'
  deduplicationWindow: 600

Cron Trigger

Runs the automation on a schedule.

Property Description
expression Cron expression — standard 5-field or 6-field with seconds (e.g. 0 9 * * 1-5). No @daily/@hourly aliases — use the numeric equivalent. Validated at config decode.
timezone IANA timezone (e.g. America/New_York). Defaults to UTC. Validated against the IANA database. 
trigger:
  type: cron
  expression: '0 9 * * 1-5'
  timezone: Europe/Paris

Record Trigger

Fires when records change in a table.

Property Description
table Name of the table to watch. Required.
events Array of create / update / delete (minimum 1). Required.
watchFields On update, only fire when one of these fields changes.
condition A condition group — only fire when the changed row matches the predicate. 
trigger:
  type: record
  table: orders
  events: [create, update]
  watchFields: [status]
  condition:
    conditions: [{ field: '{{trigger.data.status}}', operator: equals, value: paid }]

Auth Trigger

Fires on authentication lifecycle events.

Property Description
events Array of signUp, signIn, signOut, passwordReset, emailVerified (minimum 1). Required. 
trigger:
  type: auth
  events: [signUp]

Form Trigger

Fires when a top-level form (forms[].name) is submitted.

Property Description
form References forms[].name. Required. (Hard break: this used to be a page path.) See Forms. 
trigger:
  type: form
  form: contact-request

Manual Trigger

Admin-initiated execution via a button or API call.

Property Description
label Button label in the admin interface (e.g. Export Report).
inputSchema JSON Schema describing required input fields supplied at trigger time.
requiredRole Auth role required to trigger (default admin).

Manual triggers are the only triggers eligible for aiAccess (MCP invocation), since they don't fire on their own.

trigger:
  type: manual
  label: Sync inventory
  requiredRole: admin
  inputSchema: { warehouse: { type: string } }

Automation-Call Trigger

Fires when another automation invokes this one via the automation/call action — enabling sub-workflow composition.

Property Description
inputSchema Expected input contract (JSON Schema-like). If omitted, accepts any inputData from the caller. 
trigger:
  type: automation-call
  inputSchema: { customerId: { type: string } }

See Flow Control for the automation/call and automation/return actions.

Automation-Failure Trigger

Fires when a watched automation fails — composable failure handling without per-automation notification config.

Property Description
automations Array of automation names (kebab-case) to watch. If omitted, fires on any failure. 
trigger:
  type: automation-failure
  automations: [nightly-sync, billing-run]

Comment Trigger

Fires when a comment is created on a record in a comments-enabled table.

Property Description
table Name of the table with comments enabled. Required.
when approved (moderated-approved only), created (any new comment), or any. Default created.
filter { topLevelOnly, repliesOnly, mentionsOnly } (top-level and replies-only are mutually exclusive).
respectReadPermissions When true, only fire if the triggering context can read the record.

Comment triggers expose $trigger.comment.*, $trigger.record.*, $trigger.threadParticipants, and $trigger.mentions.

trigger:
  type: comment
  table: tickets
  when: created
  filter: { mentionsOnly: true }