> ## 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 webhook

> Subscribe endpoints to events, rotate signing secrets, and inspect deliveries.

Webhooks deliver events to your endpoint, signed `Vetta-Signature: v1=<hex>`. See [Webhooks](/docs/capabilities/webhooks) for the signature scheme, retry policy, and payload shapes.

## Commands

| Command                                      | Description                                               |
| -------------------------------------------- | --------------------------------------------------------- |
| `vetta webhook add`                          | Subscribe an endpoint to events.                          |
| `vetta webhook list`                         | List endpoints.                                           |
| `vetta webhook show <id>`                    | Show one endpoint.                                        |
| `vetta webhook update <id>`                  | Change the URL or events, or enable/disable the endpoint. |
| `vetta webhook rotate <id>`                  | Rotate the signing secret with an overlap window.         |
| `vetta webhook deliveries <id>`              | List delivery attempts.                                   |
| `vetta webhook delivery <id> <delivery-id>`  | Show one delivery attempt.                                |
| `vetta webhook redeliver <id> <delivery-id>` | Resend a past delivery.                                   |
| `vetta webhook test <id>`                    | Send a test delivery.                                     |
| `vetta webhook rm <id>`                      | Remove an endpoint.                                       |

<Note>
  The delete verb is **`rm`**, not `delete`. Unknown commands are a hard error, so `vetta webhook delete` exits `2` rather than removing anything.
</Note>

## add

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

| Flag       | Description                             |
| ---------- | --------------------------------------- |
| `--url`    | Receiver URL (required).                |
| `--events` | Comma-separated event names (required). |

## list & show

```bash theme={"system"}
vetta webhook list --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "whk_a2824xga8bwkbp1nh799xa75kp",
      "object": "webhook_endpoint",
      "url": "https://example.com/hook",
      "events": ["session.idle", "budget.exceeded"],
      "enabled": false,
      "created_at": "2026-08-22T16:27:28.505Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

`enabled: false` here is not a default — it is what auto-disable looks like after repeated delivery failures. Check it before assuming an endpoint is live.

## update

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

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

| Flag                     | Description              |
| ------------------------ | ------------------------ |
| `--url`                  | New receiver URL.        |
| `--events`               | Replacement event list.  |
| `--enable` / `--disable` | Turn delivery on or off. |

Only the flags you actually pass are sent, so a patch never resurrects a default. Passing none at all is an error rather than a no-op.

## rotate

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

| Flag              | Description                            |
| ----------------- | -------------------------------------- |
| `--overlap-hours` | How long the old secret keeps signing. |

Returns a **new secret, shown once**. During the overlap window both secrets sign each delivery via a multi-signature `Vetta-Signature: v1=…,v1=…` header, so a receiver can redeploy without dropping a delivery. Update your stored secret, then let the old one expire.

## deliveries, delivery & redeliver

```bash theme={"system"}
vetta webhook deliveries whk_... --limit 2
```

```json theme={"system"}
{
  "data": [
    {
      "id": "whd_3tap9jvcskr8gecfah8mbcpdfk",
      "event_id": "evt_cv21038rjn7c8p7kgwvzb43p5v",
      "event_type": "session.idle",
      "status": "failed",
      "attempts": 5,
      "response_status": 404,
      "response_snippet": "The endpoint is offline.",
      "delivered_at": null,
      "next_retry_at": null
    }
  ],
  "has_more": true,
  "next_cursor": "whd_pqs621h5jj6rwkhcyq2gbj3g3p"
}
```

`response_snippet` carries what your endpoint actually returned, which is usually enough to diagnose a failure without adding logging on your side. `next_retry_at: null` with `status: "failed"` means retries are exhausted — the delivery will not be attempted again unless you `redeliver` it.

```bash theme={"system"}
vetta webhook delivery whk_... whd_...      # one attempt, in full
vetta webhook redeliver whk_... whd_...     # send it again
vetta webhook test whk_...                  # synthetic delivery, to check wiring
```

`deliveries` takes `--limit` and `--after`; `delivery`, `redeliver`, `test`, `show`, and `rm` take no flags — only positional ids.