Triggers
What starts an automation when no one is calling — a schedule, an inbound webhook, or a manual fire — with every firing recorded.
Overview
A trigger points at something runnable — an agent, a tool, an orchestration or an eval — and says what starts it:
schedule— a 5-field cron expression in UTC, fired by the runtime;webhook— an inbound call signed with the trigger's own secret;event— a subscription to an event the upstream runtime emits internally, matched by pattern;manual— fired through this API.
Each firing is a record of its own: what started it, what it produced, and whether it succeeded. That is the difference between a trigger and a cron entry in your own infrastructure — the attempt is auditable, and the result is linked to the thing it created.
This module is a verbatim mirror of the runtime: every field, method, status code
and error shape is the runtime's own, re-rooted under the project in the path. It
serves two collections — /triggers and /trigger-firings.
How many. Counted across every project the billing owner pays for: Free
holds 3, Pro 30, Business 500; an Enterprise ceiling is set by contract.
Creating one past that answers 403 PLAN_LIMIT_REACHED with the plan, the
limit and the count used in meta, whether a direct create, a formation
deploy or an agent's tool call creates it.
How often. A schedule may not fire more often than the plan allows — hourly
on Free, every 5 minutes on Pro, every minute on Business, by contract on
Enterprise. The project's min_trigger_interval_seconds carries that floor,
set from the billing owner's plan; you can read it on
GET /v1/projects/{project_id} but not write
it. A cron whose closest two firings fall under it answers
400 TRIGGER_INTERVAL_BELOW_FLOOR with min_trigger_interval_seconds in
meta, so 0 9,17 * * * is read as eight hours rather than as twice a day.
Updating a trigger is checked the same way, and a webhook trigger has no
schedule to measure. An upgrade lowers the floor at once; a downgrade raises it
when the month turns, and a trigger stored under the old floor keeps firing
until its next update.
Run an agent on a schedule
shows the refusal on Free.
Both caps hold on every trigger a formation deploy creates
or updates, measured at the cron its parameters resolve to; a refused
trigger fails the deploy. A validate or plan creates nothing and is not
measured.
Both refusals are naturali's, not the runtime's. A cron naturali cannot
parse is forwarded, so an invalid expression is still the runtime's to refuse.
See the OpenAPI spec for the full endpoint and schema reference, or browse it rendered under API Reference → Triggers.
Data Model
Trigger
| Field | Type | Description |
|---|---|---|
id | string | |
project_id | string | |
name | string | |
description | string, nullable | |
type | manual | webhook | schedule | event | |
target_type | orchestration | agent | tool | eval | |
target_id | string | Public ID of the target resource (orchestration, agent, tool, or eval) |
action | string, nullable | Tool targets only — the action for builtin/mcp tools |
input | object, nullable | Static input, shallow-merged under fire-time input. For eval targets the effective input may carry agent_version and baseline_run_id, which are passed to the queued run. |
cron | string, nullable | 5-field cron expression (UTC). Present only for schedule triggers |
events | string[], nullable | Event triggers only: the event type patterns that fire it. |
event_resources | string[], nullable | Event triggers only: resource patterns the event must match. Null matches any resource in the project. |
event_data | object, nullable | Event triggers only: a filter the event's data must match. |
active | boolean | |
policy_ids | string[] | The policies a firing acts under: alone when nobody called the trigger, intersected with the caller's grant for a manual fire. |
next_fire_at | string (date-time), nullable | Read-only, schedule triggers only. Server-computed next fire time; null while the trigger is inactive, recomputed from now when it is re-activated |
created_at | string (date-time) | |
updated_at | string (date-time) |
tool_context is write-only: every firing forwards it to the run it starts, and
no read returns it — see A schedule carries its own tool
context. An inactive trigger neither
fires nor accepts a webhook.
TriggerFiring
| Field | Type | Description |
|---|---|---|
id | string | |
trigger_id | string | |
project_id | string | |
source | manual | webhook | schedule | event | |
status | queued | running | completed | failed | |
input | object, nullable | Effective input, after the trigger's static input is merged under the fire-time input. For an event firing the fire-time input is the event envelope a webhook delivery carries (id, event, project_id, resource_type, resource_id, data, timestamp). For every target but a tool, fired_at is the firing's own time (ISO 8601 UTC), overriding a supplied fired_at. |
result | object, nullable | { target_type, result_id, status, output } — output truncated |
error | object, nullable | Why the firing failed, when it did. |
idempotency_key | string, nullable | <event_id>:<trigger_id> for an event firing, where event_id is the id in input; <v1>:<trigger_id> for a webhook firing, from its delivery's t=,v1= signature; null otherwise. The same event reaching the same trigger twice produces one firing under this key, so a consumer reading firings can recognise a redelivery; a replayed signed delivery is refused. |
attempts | integer | Dispatch attempts started. Above 1 means an earlier attempt was interrupted before it recorded a result and the firing was redelivered — not that the target refused it, which is recorded terminally in error and never retried. |
acted_as | object, nullable | The principal the firing acted as: the trigger itself (trigger, under its policy_ids), or the caller of a manual fire (under the caller's grant ∩ policy_ids). Null for a firing refused before it was dispatched. |
started_at | string (date-time), nullable | |
completed_at | string (date-time), nullable | |
created_at | string (date-time) | |
updated_at | string (date-time) |
Key Concepts
Firing is recorded, not fire-and-forget
POST /v1/projects/{project_id}/triggers/{trigger_id}/fire
creates a firing and returns it. Read one back with
GET /v1/projects/{project_id}/trigger-firings/{firing_id},
or list one trigger's log with
GET /v1/projects/{project_id}/trigger-firings —
trigger_id is required there, so the log is always read per trigger rather than
project-wide.
result.result_id is the handle to what it produced — a
generation, an orchestration run, or an
eval run — so a scheduled job is traceable to its output
rather than to a log line.
Run an agent on a schedule
fires a new schedule by hand, follows result_id
to its generation
and reads the log.
A trigger acts under the policies it names
A firing has no caller, so it acts under the trigger's policy_ids, which names
the project's policies. It is required on
POST /v1/projects/{project_id}/triggers
and on a trigger resource in a formation template; a
create without it is refused with the runtime's validation error. You must hold
every grant of a policy you name, else 403 POLICY_GRANT_NOT_HELD. An update
without policy_ids keeps the trigger's own.
A firing acts as the trigger, not as whoever created it, so it keeps firing
after its creator is gone. The work it starts stores that authority and runs
under it to the end: a member who later resumes a run the firing started lends
it nothing. A firing whose stored authority no longer resolves records
409 WORK_AUTHORITY_MISSING in its error and runs nothing.
A negative balance stops a firing by hand
Whatever the trigger targets goes on to generate, so
POST /v1/projects/{project_id}/triggers/{trigger_id}/fire
answers 402 INSUFFICIENT_CREDIT and records no firing while the project owes
for usage already served. So does a signed
webhook call. It is the project
owner's balance. See
A negative balance stops managed generation.
A Free account that has used its plan's monthly runs answers
403 PLAN_LIMIT_REACHED with resource: "runs" here as well, on its own
credential too. See
A plan's run allowance can stop generation.
This holds however the call arrives: a call to this API or an agent's tool call.
A trigger's scheduled firings are not refused this way: they never pass through this API, so nothing here sees them. Reading the log is never refused either.
A debt turns a schedule off
Since a scheduled firing is not refused, it is stopped instead. When the
reconciliation finds the project owner's balance negative, every schedule
trigger they hold is set active: false — across all their projects, on the
same balance. A manual, webhook or event trigger is untouched: those fire
because something already refused above asked them to.
Turning one back on
is yours to do after a top-up; nothing re-enables a schedule
for you. Everything a debt stopped is listed at
GET /v1/users/me/stops, to restore
or dismiss one by one — see
Restoring what billing stopped.
Only a negative balance does this. A zero balance keeps its schedules, which is
the same line 402 INSUFFICIENT_CREDIT
is drawn on. The stop lands within one reconciliation interval of the debt
appearing, so a schedule may fire a few more times before it stops.
Static input sits under fire-time input
A trigger's input is a default: whatever the firing supplies is shallow-merged
on top. So a schedule can carry the constant part of a payload while a manual or
webhook fire varies the rest.
Every firing but a tool's also carries fired_at, its own time as an ISO 8601
UTC string (2026-08-25T12:00:00.000Z), over any supplied fired_at. It is
recorded in the firing's input, so a redelivery reads the same time. A
scheduled run builds time filters from it, such as
{ "expires_at": { "lt": { "var": "input.fired_at" } } }: lt/gt compare
strings, which orders ISO 8601 UTC strings of this form by time.
A schedule carries its own tool context
A tool that authorizes per call reads its credential from the
tool_context of
whoever started the work. A scheduled firing has no such caller, so a trigger
carries the bag itself: tool_context on the trigger is forwarded to every run
a firing starts, and each key reaches the endpoint as one
X-Naturali-Context-<key> header.
It is write-only — accepted on create and update, never returned on a read, so the record cannot be used to recover a value.
A key starting with naturali_ is the platform's and is refused
as in every tool_context
(400 INVALID_TOOL_CONTEXT_KEY, meta.keys), on create, update and fire
alike, whether over REST, from a builtin create-trigger call or as a
formation resource.
A value may be a {{secret:...}} reference rather than a literal, which is what
a stored bag should carry: the credential stays in the
secret store and only its name sits on the trigger, so rotating
the secret changes the next firing without touching the trigger. The reference
is checked against the project when it is written — one naming a secret that
does not exist is refused there, not at fire time.
A manual fire has a caller, so it may pass
tool_context of its own, shallow-merged per key over the stored bag. That half
is forwarded exactly as written: a {{secret:...}} is resolved only in the
trigger's stored bag, never in one supplied at fire time.
The webhook secret can be read at any time
GET /v1/projects/{project_id}/triggers/{trigger_id}/secret
reads the current signing secret, and
POST /v1/projects/{project_id}/triggers/{trigger_id}/rotate-secret
replaces it. Rotating invalidates the old one immediately, so update the caller
before you rotate.
A webhook trigger is called at its own URL
A webhook trigger fires when the system you connect calls
POST https://api.naturali.ai/v1/projects/{project_id}/hooks/triggers/{trigger_id}
It takes no bearer token: the caller signs with the trigger's
secret and sends
X-Naturali-Signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<body>">
over the raw body. A signature more than 300 seconds from the server's clock is
refused, and so is the same signed delivery sent twice, so a captured call
cannot be replayed. The body, at most 1 MiB of JSON, is the fire-time input; a
value that is not an object arrives as { "payload": … }. The SDK and the CLI
have no method for it, since the caller is not a client of this API.
import { createHmac } from 'node:crypto';
const body = JSON.stringify({ order_id: 'ord_123' });
const t = Math.floor(Date.now() / 1000);
const digest = createHmac('sha256', process.env.TRIGGER_SECRET!)
.update(`${t}.${body}`)
.digest('hex');
await fetch(
'https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/hooks/triggers/trg_V1StGXR8Z5jdHi6B',
{
method: 'POST',
headers: {
'Content-Type': 'application/json',
'X-Naturali-Signature': `t=${t},v1=${digest}`,
},
body,
}
);
| Status | When |
|---|---|
202 | Accepted: { firing_id, trigger_id, status }. The firing runs in the background; read it back by firing_id. |
404 | No such project, or no webhook trigger by that id in it. |
401 | The signature is missing, not made with the current secret, or its t is more than 300 seconds off. |
402 / 403 | Signed, but the owner's balance or run allowance refuses it. |
409 | The trigger is inactive (TRIGGER_NOT_ACTIVE), or this timestamped delivery was already accepted (HOOK_DELIVERY_REPLAYED). |
400 | The body is not JSON, or the input does not fit the target. |
413 | The body is over 1 MiB. |
Event triggers
An event trigger subscribes directly to the upstream runtime's internal event
bus instead of receiving a signed webhook call — the same event, delivered
in-process rather than as a network round trip back into the API. Firing works
the same as any other trigger: a TriggerFiring is created, and its input is
the event's payload.
Each events entry uses the same grammar as a webhook subscription's events
entries: documents.ingested matches that event only, documents.* matches
every event in that namespace, and * matches everything the project emits.
An event fires the trigger only when its policy_ids may read the resource the
event is about: the resource's Get action on the event's SRN, such as
memories:GetMemory on srn:<project_id>:memory:<memory_id> or
documents:GetDocument on a document. A custom event from an orchestration's
emit_event node is about its run (orchestrations:GetRun). A
create or
update whose policy_ids cannot read a
platform namespace its events subscribe to is 400 EVENTS_UNREADABLE.
A policy that cannot read one event's resource records no firing and no error
for it, so grant the read beside the target's action:
{
"statement": [
{
"effect": "Allow",
"action": ["tools:CallTool"],
"resource": ["srn:proj_V1StGXR8Z5jdHi6B:tool:tool_V1StGXR8Z5jdHi6B"]
},
{
"effect": "Allow",
"action": ["memories:GetMemory"],
"resource": ["srn:proj_V1StGXR8Z5jdHi6B:memory:*"]
}
]
}
Delivery is best-effort and unordered — the runtime's event bus makes no
stronger guarantee, so an event trigger is for reactive automation whose value
is promptness, not for work that must not be lost. Keep a schedule trigger
over the same condition as a backstop when it must not be lost; the two
compose, and a target that is idempotent per resource makes the overlap
harmless.
Because a reactive edge can feed itself, two guards apply that do not apply to any other trigger type:
- A causal loop is refused, not run. Every event carries the chain of
trigger firings that produced it. A trigger refuses to extend a chain that
already names it, or one that has already run several hops deep — either
refusal records a
failedfiring and files anevent_trigger_loopexception so the loop is triaged rather than merely stopped. - Quota admission runs before dispatch. An event trigger never passes through the same request path an API call does, so its firing is checked against the project's quotas before it runs — a wide pattern on an expensive target is still bounded.
Scheduling an eval is the point of eval targets
A schedule trigger against an eval is how a suite runs
nightly instead of when someone remembers: the eval run it produces carries
trigger_id, so a scored regression is attributable to the schedule that found
it.
Who may do what
Every route needs any project member, except the webhook call, which needs the trigger's signature instead.
Examples
Schedule a nightly eval
- CLI
- SDK
- curl
naturali create-trigger \
--project-id proj_V1StGXR8Z5jdHi6B \
--name nightly-billing-evals \
--type schedule \
--cron "0 3 * * *" \
--target-type eval \
--target-id eval_V1StGXR8Z5jdHi6B \
--policy-ids pol_V1StGXR8Z5jdHi6B
const { data: trigger } = await naturali.triggers.createTrigger({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
body: {
name: 'nightly-billing-evals',
type: 'schedule',
cron: '0 3 * * *',
target_type: 'eval',
target_id: 'eval_V1StGXR8Z5jdHi6B',
policy_ids: ['pol_V1StGXR8Z5jdHi6B'],
},
});
console.log(trigger?.next_fire_at);
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/triggers \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"name": "nightly-billing-evals",
"type": "schedule",
"cron": "0 3 * * *",
"target_type": "eval",
"target_id": "eval_V1StGXR8Z5jdHi6B",
"policy_ids": ["pol_V1StGXR8Z5jdHi6B"]
}'
Fire one by hand with extra input
- CLI
- SDK
- curl
naturali fire-trigger \
--project-id proj_V1StGXR8Z5jdHi6B \
--trigger-id trg_V1StGXR8Z5jdHi6B \
--input '{ "agent_version": 4 }'
const { data: firing } = await naturali.triggers.fireTrigger({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
trigger_id: 'trg_V1StGXR8Z5jdHi6B',
},
body: { input: { agent_version: 4 } },
});
console.log(firing?.status, firing?.result?.result_id);
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/triggers/trg_V1StGXR8Z5jdHi6B/fire \
-H "Authorization: Bearer $NATURALI_TOKEN" \
-H "Content-Type: application/json" \
-d '{ "input": { "agent_version": 4 } }'
Audit what one trigger has done
- CLI
- SDK
- curl
naturali list-trigger-firings \
--project-id proj_V1StGXR8Z5jdHi6B \
--trigger-id trg_V1StGXR8Z5jdHi6B \
--limit 20
const { data: firings } = await naturali.triggers.listTriggerFirings({
path: { project_id: 'proj_V1StGXR8Z5jdHi6B' },
query: { trigger_id: 'trg_V1StGXR8Z5jdHi6B', limit: 20 },
});
curl "https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/trigger-firings?trigger_id=trg_V1StGXR8Z5jdHi6B&limit=20" \
-H "Authorization: Bearer $NATURALI_TOKEN"
Rotate the webhook secret
- CLI
- SDK
- curl
naturali rotate-trigger-secret \
--project-id proj_V1StGXR8Z5jdHi6B \
--trigger-id trg_V1StGXR8Z5jdHi6B
const { data: rotated } = await naturali.triggers.rotateTriggerSecret({
path: {
project_id: 'proj_V1StGXR8Z5jdHi6B',
trigger_id: 'trg_V1StGXR8Z5jdHi6B',
},
});
curl -X POST https://api.naturali.ai/v1/projects/proj_V1StGXR8Z5jdHi6B/triggers/trg_V1StGXR8Z5jdHi6B/rotate-secret \
-H "Authorization: Bearer $NATURALI_TOKEN"