Reference

Triggers

Inbound webhook endpoints that start an agent or workflow run when an external event arrives. Verified by signature, idempotent, rate-limited and audited, with no human at the keyboard.

What triggers are for

A trigger turns an external event, such as a new ticket, a form submission or a provider webhook, into a governed run of one of your agents or workflows. Each trigger publishes a unique POST endpoint that an event source calls. The caller proves its authority cryptographically rather than by logging in, so there is no session and no human initiator behind the run.

Every trigger is bound to exactly one target: an agent or a workflow. When the endpoint is called and the request passes the checks below, SyftOS dispatches a run of that target under the same governance as any other run.

Creating a trigger

From the Inbound triggers page, choose New trigger and provide:

• Name: a human label, e.g. Jira ticket intake.
• Description: optional note on what the trigger does.
• Target type: Agent or Workflow.
• Target: the specific agent or workflow to run.

On creation SyftOS shows the endpoint URL and the signing secret together, once. This is the only time the secret is displayed. It is stored encrypted and never shown again. Copy it immediately and store it with the event source that will call the endpoint.

Endpoint, secret and headers

The endpoint is a public POST URL keyed by the trigger's slug. To authenticate a call, the event source signs the raw request body with HMAC-SHA256 keyed by the signing secret and sends the resulting hex digest in the signature header. The exact header names are shown on the trigger page (configured per deployment).

• Signature header: carries the HMAC-SHA256 hex digest of the raw body. The signature is verified before any state changes, so an unsigned or forged caller learns nothing and consumes no idempotency key.
• Idempotency header: optional. Send a unique value per logical event for at-most-once dispatch; a repeated key is treated as a replay rather than a fresh run.

The request body is decoded as JSON. By default the whole payload is passed to the run; in a trigger's Configuration you can instead nominate a top-level payload key whose value becomes the run prompt, and choose whether to pass the full payload through. An invalid or empty body is not an error. The signature is what authorises the call, not the shape of the payload.

If you suspect a secret has leaked, open the trigger and Rotate secret. As with creation, the new secret is shown once; update your event source before the old one is invalidated.

Activations and outcomes

Every call to the endpoint, accepted or refused, is recorded as an activation in the trigger's history, so you can see exactly what hit it and what happened. Each row shows when it occurred, the outcome, a detail, and the idempotency key.

• Dispatched: the call was accepted and a run was started; the detail links the spawned agent or workflow run.
• Rejected: the call was refused, with a stable reason: invalid signature, duplicate (idempotent replay), token unauthorised, trigger disabled, rate limited, or dispatch refused (for example a suspension, plan limit or budget).

The endpoint never echoes the body, the secret, the token or any tenant detail back to an unauthenticated caller. It returns only the activation id and the run id on success, or the rejection reason.

Enabling, disabling and governance

Enable / Disable is the instant off switch: a disabled trigger keeps its endpoint and configuration but refuses every call until re-enabled. Delete removes the trigger and revokes its bound token, so the endpoint stops working permanently. This cannot be undone.

Managing triggers (creating, editing, enabling/disabling, rotating and deleting) sits behind the triggers.manage permission, granted to owner and admin roles. A trigger is scoped to its tenant, so another tenant's trigger is simply not found.

At runtime the trigger acts through a tenant-scoped, ability-bound token rather than a session role. If that token lacks the ability required by the dispatched run, the call is rejected as token unauthorised — triggers cannot quietly escalate what their target is allowed to do.

Next steps