Skip to main content

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.

A plan caps how many triggers you hold, and how often each fires

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​

FieldTypeDescription
idstring
project_idstring
namestring
descriptionstring, nullable
typemanual | webhook | schedule | event
target_typeorchestration | agent | tool | eval
target_idstringPublic ID of the target resource (orchestration, agent, tool, or eval)
actionstring, nullableTool targets only — the action for builtin/mcp tools
inputobject, nullableStatic 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.
cronstring, nullable5-field cron expression (UTC). Present only for schedule triggers
eventsstring[], nullableEvent triggers only: the event type patterns that fire it.
event_resourcesstring[], nullableEvent triggers only: resource patterns the event must match. Null matches any resource in the project.
event_dataobject, nullableEvent triggers only: a filter the event's data must match.
activeboolean
policy_idsstring[]The policies a firing acts under: alone when nobody called the trigger, intersected with the caller's grant for a manual fire.
next_fire_atstring (date-time), nullableRead-only, schedule triggers only. Server-computed next fire time; null while the trigger is inactive, recomputed from now when it is re-activated
created_atstring (date-time)
updated_atstring (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​

FieldTypeDescription
idstring
trigger_idstring
project_idstring
sourcemanual | webhook | schedule | event
statusqueued | running | completed | failed
inputobject, nullableEffective 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.
resultobject, nullable{ target_type, result_id, status, output } — output truncated
errorobject, nullableWhy the firing failed, when it did.
idempotency_keystring, 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.
attemptsintegerDispatch 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_asobject, nullableThe 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_atstring (date-time), nullable
completed_atstring (date-time), nullable
created_atstring (date-time)
updated_atstring (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,
}
);
StatusWhen
202Accepted: { firing_id, trigger_id, status }. The firing runs in the background; read it back by firing_id.
404No such project, or no webhook trigger by that id in it.
401The signature is missing, not made with the current secret, or its t is more than 300 seconds off.
402 / 403Signed, but the owner's balance or run allowance refuses it.
409The trigger is inactive (TRIGGER_NOT_ACTIVE), or this timestamped delivery was already accepted (HOOK_DELIVERY_REPLAYED).
400The body is not JSON, or the input does not fit the target.
413The 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 failed firing and files an event_trigger_loop exception 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​

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

Fire one by hand with extra input​

naturali fire-trigger \
--project-id proj_V1StGXR8Z5jdHi6B \
--trigger-id trg_V1StGXR8Z5jdHi6B \
--input '{ "agent_version": 4 }'

Audit what one trigger has done​

naturali list-trigger-firings \
--project-id proj_V1StGXR8Z5jdHi6B \
--trigger-id trg_V1StGXR8Z5jdHi6B \
--limit 20

Rotate the webhook secret​

naturali rotate-trigger-secret \
--project-id proj_V1StGXR8Z5jdHi6B \
--trigger-id trg_V1StGXR8Z5jdHi6B