vetta webhook

Webhooks deliver events to your endpoint, signed Vetta-Signature: v1=<hex>. See 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.

The delete verb is rm, not delete. Unknown commands are a hard error, so vetta webhook delete exits 2 rather than removing anything.

add

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

vetta webhook list --limit 2

{
  "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:

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

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

vetta webhook deliveries whk_... --limit 2

{
  "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.

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.

Getting started

Building & running

Organization

Identity

vetta webhook

Commands

add

list & show

update

rotate

deliveries, delivery & redeliver

​Commands

​add

​list & show

​update

​rotate

​deliveries, delivery & redeliver

Commands

add

list & show

update

rotate

deliveries, delivery & redeliver