webhook

owlette webhook is the planned top-level operator noun for cross-product event subscriptions. Site-scoped commands are expected to require --site or a site-scoped API key when this surface ships.

planned verbs

create (planned)

owlette webhook create --site <s> --url <url> --events <csv> [--description <text>]

New subscription. The signing secret is shown once in the response. Backing endpoint: POST /api/webhooks?siteId=<s>.

list (planned)

owlette webhook list --site <s>

List subscriptions on a site. Backing endpoint: GET /api/webhooks?siteId=<s>.

get (planned)

owlette webhook get <id> --site <s>

Subscription detail. Response never includes the secret. Backing endpoint: GET /api/webhooks/{id}?siteId=<s>.

update (planned)

owlette webhook update <id> --site <s> [--url <url>] [--events <csv>] [--paused]

Partial update. Backing endpoint: PATCH /api/webhooks/{id}?siteId=<s>.

delete (planned)

owlette webhook delete <id> --site <s> [--yes]

Soft-delete with a 30-day tombstone. Backing endpoint: DELETE /api/webhooks/{id}?siteId=<s>.

rotate-secret (planned)

owlette webhook rotate-secret <id> --site <s>

Issue a new signing secret with a 24-hour grace window on the old one. Backing endpoint: POST /api/webhooks/{id}/rotate-secret?siteId=<s>.

deliveries (planned)

owlette webhook deliveries <id> --site <s> [--limit <n>] [--cursor <token>]

30-day delivery history. Backing endpoint: GET /api/webhooks/{id}/deliveries?siteId=<s>.

delivery get (planned)

owlette webhook delivery get <id> <deliveryId> --site <s>

Full request/response transcript for one delivery. Backing endpoint: GET /api/webhooks/{id}/deliveries/{deliveryId}?siteId=<s>.

retry (planned)

owlette webhook retry <id> <deliveryId> --site <s>

Re-enqueue a single delivery. Backing endpoint: POST /api/webhooks/{id}/deliveries/{deliveryId}/retry?siteId=<s>.

probe (planned noun)

owlette webhook probe --site <s> --url <url> --event <name> [--payload <json>]

Fire a signed synthetic event at an arbitrary URL without creating a subscription. Backing endpoint: POST /api/webhooks/probe?siteId=<s>.

listen (shipped top-level; planned noun alias)

owlette listen --site <s> --forward-to <url> [--events <csv>]

Shipped top-level helper. It opens GET /api/events/stream?siteId=<s> and forwards received SSE events. In the current developer preview the stream emits connected and keepalive liveness events only; production event fanout is deferred. A future owlette webhook listen alias is planned but not shipped.

trigger (shipped top-level; planned noun alias)

owlette trigger <event> --site <s> --to <url> [--payload <json>] [--via-api]

Shipped top-level helper. Without --via-api, it posts a canned payload directly to --to. With --via-api, it calls POST /api/webhooks/probe?siteId=<s>. A future owlette webhook trigger alias is planned but not shipped.

planned noun aliases

Current shipped commands:

owlette listen --site site-1 --forward-to http://localhost:3000/hooks
owlette trigger version.published --site site-1 --to http://localhost:3000/hooks

Possible future noun aliases:

owlette webhook listen --site site-1 --forward-to http://localhost:3000/hooks
owlette webhook trigger version.published --site site-1 --to http://localhost:3000/hooks

These aliases are planned, not available in the current CLI, and there is no committed sunset date for the shipped top-level forms.

exit codes

• 0 - success
• 1 - generic error (network, 5xx, signature verification failure on probe)
• 2 - usage error (missing --site, malformed --events csv, bad --payload json)

notes

• scope: list/detail/deliveries use site:<siteId>:read; create/update/delete/rotate/probe/retry use site:<siteId>:write.
• secret handling: create and rotate-secret are the only places the secret is returned. it is never readable again.
• signing: deliveries use Roost-Signature: t=<unix>,v1=<hmac_sha256_hex>.
• contract: web/openapi.yaml is authoritative for request/response shapes.