# 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. ```yaml 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`. ```yaml 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. | ```yaml 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. | ```yaml 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.** | ```yaml 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](/en/docs/forms-overview). | ```yaml 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. ```yaml 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. | ```yaml trigger: type: automation-call inputSchema: { customerId: { type: string } } ``` See [Flow Control](/en/docs/automation-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. | ```yaml 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`. ```yaml trigger: type: comment table: tickets when: created filter: { mentionsOnly: true } ``` ## Related Pages - [Automations Overview](/en/docs/automations-overview) — anatomy and template variables. - [Actions Overview](/en/docs/automation-actions-overview) — what runs after a trigger fires. - [Webhooks (tables)](/en/docs/table-webhooks) — _outgoing_ table webhooks (distinct from inbound webhook triggers). - [Flow Control](/en/docs/automation-flow-control) — `automation/call` and `automation/return`.