Skip to main content
The trigger router turns inbound events into agent runs. A trigger subscription binds a source (+ optional filter) to a target agent run; when a matching event fires, the router wakes the bound agent and records a delivery status. See the architecture for the full model.
Triggers wake an agent. Webhooks do the opposite — they POST an outbound signed callback to your backend. Both fire on the same inbound events; use whichever (or both) fits your flow.

​
Sources

GET /v1/triggers/sources is the source of truth.

​
Create a trigger

  • filter — event_types/event_type match the dotted type; any other key matches the same-named field in the payload (to, from, e164, …). Omit for “every event of this source”.
  • target — { prompt }, or { promptTemplate } with {{type}}, {{source}}, {{payload}} substitutions, plus an optional profileName.
  • delivery — auto (default), sidecar (cloud runtime), or device (a bound Tower box, via the encrypted device relay).

​
Test the wiring

Fire a synthetic event through the router without waiting for a real provider webhook:

​
Inbound hook endpoints

For arbitrary third-party events (a GitHub push, a Stripe event, your own backend), create a per-agent inbound endpoint. Each endpoint has its own signing secret; inbound POSTs are HMAC-verified and routed through the same trigger router.
Signatures are timestamped to make them replay-safe: a body-only signature can be captured and re-POSTed forever. Send both headers — X-Naive-Timestamp (unix seconds) and X-Naive-Signature — and sign the string `${timestamp}.${rawBody}`, not the body alone. A request missing either header is rejected, and the timestamp must be within 5 minutes of server time.
A sha256= or v1, prefix on the signature is stripped automatically, so GitHub’s X-Hub-Signature-256 format works as-is — but it must still be accompanied by X-Naive-Timestamp. Rotate the secret with POST /v1/hooks/{id}/rotate-secret.
Encrypted box delivery. When the bound agent lives on a Tower box, the event gateway routes the wake over the device relay. If the device registered an X25519 encryption key at claim, the payload is sealed to the box (ECIES: ephemeral X25519 → HKDF → AES-256-GCM) before it is stored or relayed — so a tenant’s inbound mail/SMS is never readable at rest in the cloud. Devices without a key fall back to plaintext relay (unchanged).

​
Delivery status

Every routed event is observable — including events that matched no subscription (recorded as no_match, so a silent drop is visible):
Statuses advance received → queued → delivered → processed | failed.

​
Billing

Free — the agent run the trigger dispatches bills as any other run.