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

# vetta deploy & webhook

> Schedule agents with cron and subscribe to events.

Manage [deployments](/docs/capabilities/deployments) (scheduled agents) and [webhooks](/docs/capabilities/webhooks) (event subscriptions).

## Deployments

| Command                    | Description                                                              |
| -------------------------- | ------------------------------------------------------------------------ |
| `vetta deploy create`      | Create a scheduled deployment.                                           |
| `vetta deploy list`        | List deployments.                                                        |
| `vetta deploy show <id>`   | Show a deployment.                                                       |
| `vetta deploy update <id>` | Change the schedule, prompt, budget, window, persona, or pinned version. |
| `vetta deploy run <id>`    | Fire once, now.                                                          |
| `vetta deploy runs <id>`   | List past runs.                                                          |
| `vetta deploy pause <id>`  | Pause the schedule.                                                      |
| `vetta deploy resume <id>` | Resume the schedule.                                                     |
| `vetta deploy delete <id>` | Delete the deployment.                                                   |

```bash theme={"system"}
vetta deploy create --agent nightly-triage \
  --cron "0 9 * * *" \
  --budget-usd 5 \
  --window priority \
  --agent-version 4 \
  --identity ava-sales \
  --prompt "Summarize what changed in main overnight."
vetta deploy runs nightly-triage --human
```

| Flag              | Description                                                                                                                                                                    |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `--agent`         | Agent to run (required).                                                                                                                                                       |
| `--cron`          | Cron expression in UTC (required).                                                                                                                                             |
| `--budget-usd`    | Per-run budget ceiling (required). Decimal-dollar string → `cap_micro_usd` on the wire.                                                                                        |
| `--agent-version` | Pin runs to a specific agent version. Optional; defaults to the agent's `current_version`.                                                                                     |
| `--prompt`        | Instruction sent to each scheduled session.                                                                                                                                    |
| `--window`        | Completion window for scheduled runs: `immediate` \| `priority`.                                                                                                               |
| `--timezone`      | IANA timezone the cron expression is evaluated in. Defaults to UTC.                                                                                                            |
| `--on-idle`       | What to do when a scheduled run goes idle.                                                                                                                                     |
| `--identity`      | The [persona](/docs/identity/personas) each fire speaks as — an `idn_` id or its name. The agent must already hold a grant to it. Without one a scheduled run speaks as no persona. |

`update` takes the same flags as `create` except `--agent`; only the flags you pass are changed.

<Note>
  Pin `--agent-version` for a staged rollout or rollback: scheduled runs stay on that immutable config until you re-pin, instead of jumping to `current_version` on the next fire.
</Note>

## Webhooks

Full reference: [`vetta webhook`](/docs/cli/webhook).

| Command                                   | Description                                                          |
| ----------------------------------------- | -------------------------------------------------------------------- |
| `vetta webhook add`                       | Subscribe an endpoint to events.                                     |
| `vetta webhook list`                      | List webhooks.                                                       |
| `vetta webhook show <id>`                 | Show a webhook endpoint.                                             |
| `vetta webhook update <id>`               | Change `--url`/`--events`, or `--disable` / `--enable` the endpoint. |
| `vetta webhook rotate <id>`               | Rotate the signing secret with an overlap window.                    |
| `vetta webhook deliveries <id>`           | List delivery attempts (status, response code, retries).             |
| `vetta webhook delivery <id> <delivery>`  | Show one delivery attempt.                                           |
| `vetta webhook redeliver <id> <delivery>` | Manually resend a past delivery.                                     |
| `vetta webhook rm <id>`                   | Remove a webhook.                                                    |
| `vetta webhook test <id>`                 | Send a test delivery.                                                |

```bash theme={"system"}
vetta webhook add \
  --url https://example.com/hooks/vetta \
  --events session.idle,message.completed,budget.exceeded
```

### Pause & update

Webhooks toggle with `enable`/`disable` (a config flag on the endpoint), distinct from deployment schedule `pause`/`resume`:

```bash theme={"system"}
vetta webhook update whk_01H... --disable          # stop delivering; keep the endpoint
vetta webhook update whk_01H... --enable
vetta webhook update whk_01H... --events session.idle,session.usage
```

### Rotate the signing secret

```bash theme={"system"}
vetta webhook rotate whk_01H... --overlap-hours 24
```

Returns a **new** secret (shown once). During the overlap window both the old and new secrets sign each delivery via a multi-signature `Vetta-Signature: v1=…,v1=…` header, so your verifier keeps accepting deliveries with zero drops. Update your stored secret, then let the old one expire. The SDK `unwrap` helper validates either signature automatically.

### Delivery log & redelivery

```bash theme={"system"}
vetta webhook deliveries whk_01H... --human
vetta webhook redeliver whk_01H... whd_01H...
```

```json theme={"system"}
{
  "id": "whd_01H...",
  "event_id": "evt_01H...",
  "event_type": "session.idle",
  "status": "failed",
  "attempts": 3,
  "response_status": 500,
  "delivered_at": null,
  "next_retry_at": "2026-08-20T18:10:00Z"
}
```

See [Webhooks](/docs/capabilities/webhooks) for the signature scheme, retry/auto-disable policy, and payload shapes.