Docs / Agents

Triggers and automation

Schedules, webhooks and alert-to-agent workflows that start agent work without a person opening a new turn.

A trigger starts agent work without a person sending a message. Manage triggers in Settings → Triggers, or ask an agent to create or update one. Check for an existing trigger for the same job before adding another.

Schedules use UTC

Schedules use standard 5-field cron expressions, evaluated in UTC, not the computer's local time. Convert the time you mean, and check the next runs.

For example, 09:00 in a fixed UTC−3 timezone is 12:00 UTC, so a daily run uses 0 12 * * *. For timezones with daylight saving time, update the schedule when the offset changes. Invalid expressions are rejected.

Webhooks

A webhook trigger accepts HTTP POST at its generated URL. Send its secret in the X-Webhook-Secret header. A missing or wrong secret is rejected. The secret is shown only once, when the trigger is created.

curl -X POST '<your-trigger-webhook-url>' \
  -H 'X-Webhook-Secret: <your-trigger-secret>' \
  -H 'Content-Type: application/json' \
  -d '{"alert":"high cpu"}'

This is a placeholder example. Don't put a real secret in your shell history. Set secrets in your sender's secure fields. Senders that can't set headers can use ?secret= in the URL, but URLs leak more easily through logs. Prefer the header, and rotate a secret that leaked.

A webhook accepts work before the agent finishes. An accepted response does not mean the investigation succeeded. By default, a trigger runs at most once every 60 seconds; deliveries inside that window are acknowledged but not run. You can change or turn off this cooldown per trigger. It protects against repeated runs, not against someone who has the secret.

Message templates and incidents

Give each trigger a bounded job, a runtime, credentials and a destination. Webhook payload fields can be used in the message template. Treat incoming payload text as data, not as permission to do unrelated work. Incident workflows can reuse the open incident conversation instead of starting a new one for each retry.

A Watch wires an existing provider alert to a trigger and an action. A Watch Group puts 2 to 50 related items behind one webhook and counts as one trigger. Each person can have up to 50 triggers, and each team up to 500.

For Slack delivery, pick the exact channel or DM. A complete Watch needs the provider's notification set up, read back, tested and its cleanup recorded. Creating a trigger alone is not enough.

Permissions for unattended work

Conversations started by automation use Full Access, since nobody is there to answer a prompt. Events in an existing conversation keep its owner's mode. Auto Mode requests can time out when nobody is around. See Auto Mode and Full Access.

Don't assume every automated change waits for a plan. A trigger may have nowhere to show one. Limit provider permissions and selected credentials, and say "investigate only" when that is what you want. A prompt is not an IAM restriction.

Verify, pause and remove

Check the next scheduled run, or send a bounded test delivery. Verify the resulting session and the notification, not only that the request was accepted. Disable a trigger to pause it for a while. Deleting a Watch can require cleaning up resources on the provider's side. Remove only the wiring recorded as owned by that Watch, and keep a note of any manual cleanup left.

A shell process, terminal or background watcher is not a saved trigger and does not survive every runtime restart. Use a trigger or a provider monitor for durable future work.