Webhook & Cron Triggers
The two triggers that fire without anyone using your app: an external system calling in, or the clock.
Webhook Trigger
Exposes an HTTP endpoint at /api/automations/{name}/webhook that starts the automation when hit.
trigger:
type: webhook
method: [POST]
auth: { type: hmac, secret: $env.STRIPE_SIGNING_SECRET, algorithm: sha256 }
deduplicationKey: '{{trigger.data.body.id}}'
deduplicationWindow: 600| Property | Description |
|---|---|
method |
HTTP method(s) to accept — GET/POST/PUT/PATCH/DELETE, or a non-empty array. Required. |
secret |
Secret for HMAC signature verification (e.g. $env.WEBHOOK_SECRET). |
respondImmediately |
When true, respond 202 at once. Omitted, the request waits for the run to complete. |
auth |
Inbound auth config — type is bearer, apiKey, hmac, or basic (see below). |
response |
Custom response: statusCode or status (100–599), body (string template or object), headers. |
requestSchema |
JSON Schema validating the request body. |
querySchema |
JSON Schema validating query parameters. |
rateLimit |
{ maxRequests, windowSeconds } — window is accepted as an alias for windowSeconds. |
deduplicationKey |
Template computing a dedup key (e.g. "{{trigger.data.body.orderId}}") — repeats in the window are dropped. |
deduplicationWindow |
Dedup window in seconds. Defaults to 300. |
respondImmediately is off by default — the caller waits. Omitting it takes the synchronous path, so a slow automation becomes a slow HTTP response for the sender. Set it to true for fire-and-forget receivers (Stripe, GitHub) that only need a fast 202.
Inbound authentication
auth.type is one of bearer, apiKey, hmac, basic. The credential fields — token, prefix, key, header, secret, algorithm, username, password — are all optional and unconditioned by type, and algorithm is a free string rather than an enum. Nothing validates that a bearer block actually carries a token, so an incomplete block passes sovrium validate and fails at request time. All credential values support $env.VAR.
Webhook context
The payload is not at {{trigger.body}}. Available paths are {{trigger.data.body.*}}, {{trigger.data.headers.*}}, {{trigger.data.query.*}}, plus {{trigger.data.method}}, {{trigger.data.path}} and {{trigger.data.ip}}. Scalar body fields are additionally flattened to {{trigger.data.<field>}}.
Cron Trigger
Runs the automation on a schedule.
trigger:
type: cron
expression: '0 9 * * 1-5'
timezone: Europe/Paris| Property | Description |
|---|---|
expression |
Cron expression — standard 5-field, or 6-field with seconds. Required. Validated when the config is decoded. |
timezone |
IANA timezone (e.g. America/New_York). Defaults to UTC. Validated against the IANA database. |
There are no @daily / @hourly / @weekly aliases — write the numeric equivalent (0 0 * * *, 0 * * * *). A step of zero (*/0) is rejected. Because both the expression and the timezone are validated offline, a typo fails sovrium validate rather than producing an automation that silently never runs.
Set timezone whenever the schedule is meant to track human working hours: 0 9 * * 1-5 in UTC drifts an hour against Paris twice a year, while the same expression in Europe/Paris stays at 09:00 local through both daylight-saving transitions.
Related Pages
- Triggers Overview — the nine trigger types at a glance.
- HTTP & Webhook Actions — calling out, and the
webhook/responseaction. - Table Webhooks — outgoing table webhooks, the inverse direction.
- Automation Runs — inspecting and replaying what a trigger started.
- Automation Environment Variables — the
$env.VARvalues credentials read from.
Last updated September 1, 2026
This documentation was written with AI, so errors or outdated content are possible. Sovrium is in beta. Contributions and corrections are welcome.