> ## 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](https://vetta.sh/docs/capabilities/deployments.md) (scheduled agents) and [webhooks](https://vetta.sh/docs/capabilities/webhooks.md) (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 agt_01j8rk2vq6m4zx9kp7n3c5hwae \
  --cron "0 9 * * *" \
  --budget-usd 5 \
  --window priority \
  --agent-version 4 \
  --identity ava-sales \
  --prompt "Summarize what changed in main overnight."
vetta deploy runs dep_01j8rs4vm6k2xq9zn3c7h5wtpb --human
```

| Flag | Description |
| - | - |
| `--agent` | Agent to run (required). |
| `--cron` | Cron expression (required), evaluated in `--timezone` — the organization's timezone when omitted, not UTC. |
| `--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 the organization's timezone. |
| `--on-idle` | What to do when a scheduled run goes idle. |
| `--identity` | The [persona](https://vetta.sh/docs/identity/personas.md) 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.

## Webhooks

Full reference: [`vetta webhook`](https://vetta.sh/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](https://vetta.sh/docs/capabilities/webhooks.md) for the signature scheme, retry/auto-disable policy, and payload shapes.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.