> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nuphos.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers & automation

> Run the agent automatically — on a schedule, from a webhook, or from a database alert — with a message template that seeds each run.

Triggers let the agent run **without you starting a session**. Each trigger
carries a **message template** — the prompt that seeds every run, like *"Check the
health of the production cluster and flag anything unusual."* There are three
kinds: **cron**, **webhook**, and **database alert**.

## Cron triggers

A cron trigger runs the agent on a **schedule** you define with a standard
**5-field cron expression**.

| Expression     | Runs                  |
| -------------- | --------------------- |
| `0 9 * * MON`  | Every Monday at 09:00 |
| `*/15 * * * *` | Every 15 minutes      |
| `0 * * * *`    | Hourly, on the hour   |

The expression is validated when you save the trigger, so an invalid schedule is
rejected up front.

<Note>
  Cron triggers depend on the scheduler being enabled on your Nuphos backend. If
  it isn't available, the app warns you when you try to create one — webhook
  triggers are unaffected.
</Note>

## Webhook triggers

A webhook trigger runs the agent when it receives an **HTTP POST** — wire it to CI,
an alerting tool, or any system that can call a URL. Each webhook trigger has its
own URL and **secret**, both shown in the trigger's details.

Authenticate the request with the secret in an **`X-Webhook-Secret`** header:

```bash theme={null}
curl -X POST "<your-trigger-webhook-url>" \
  -H "X-Webhook-Secret: <your-trigger-secret>" \
  -H "Content-Type: application/json" \
  -d '{"alert": "high cpu on api-prod"}'
```

* The secret is compared in constant time; a missing or wrong secret returns
  `401`.
* Senders that cannot set headers can pass it as a **`?secret=`** query parameter
  instead — the same secret-in-URL convention Slack and Discord webhooks use.
  Prefer the header: query strings are routinely written to proxy and server
  access logs, kept in browser history, and forwarded in `Referer` headers, so a
  secret in the URL leaks in places a header does not. Use it only for senders
  that give you no choice, and rotate that trigger's secret if the URL is ever
  pasted somewhere shared.
* The body can be JSON or plain text — it's passed along to the run.
* Execution is fire-and-forget: the webhook returns quickly while the agent runs
  in the background.
* A **60-second cooldown** applies per trigger. Every accepted delivery starts a
  full agent session, so a flapping alert or a sender retry storm must not become
  one session per retry. Adjust or disable it per trigger.

<Warning>
  Treat the webhook secret like a credential. Anyone with the URL and secret can
  trigger an agent run against your infrastructure.
</Warning>

## Database-alert triggers

A [database connection](/connectors/overview) can watch a query and fire the
agent when the result crosses a threshold you set. These triggers are created
from the connection's monitoring page rather than the trigger list, but they run
the agent the same way.

## Watch Groups

A **Watch Group** bundles related monitors behind a single webhook ingress, so a
set of alert rules that mean one thing to you does not become one trigger each.
A group holds between 2 and 50 members and consumes a single quota slot.

## Limits

| Limit                         | Value                          |
| ----------------------------- | ------------------------------ |
| Triggers per person           | 50                             |
| Triggers per team             | 500                            |
| Webhook cooldown, per trigger | 60s (configurable, 0 disables) |

A Watch Group counts as one, however many members it has.

## What a triggered run can do

A triggered run behaves like any other session: it can investigate, and it can
propose [plans](/agent/plans) that still require human approval before any change
executes. Automation schedules the *work*, not unattended changes.