xeroctl webhooks
Manage webhook subscriptions for event notifications. Webhooks are project-scoped and do not require an endpoint slug. Part of the xeroctl CLI.
Overview
Webhooks let you receive real-time event notifications via HTTP POST requests to a URL of your choice. When a subscribed event occurs in your project, the platform delivers a signed payload to your endpoint.
The webhooks command uses a unified flag-based interface rather
than named subcommands. The action is determined by which flag is present
(--create, --update, --delete,
--test, --deliveries). Only one action flag
may be specified at a time.
Usage Pattern
xeroctl webhooks # List all webhooks
xeroctl webhooks <id> # Show webhook details
xeroctl webhooks --create --url <url> --events <e> # Create a webhook
xeroctl webhooks <id> --update --url <url> # Update a webhook
xeroctl webhooks <id> --delete # Delete a webhook
xeroctl webhooks <id> --test # Send a test event
xeroctl webhooks <id> --deliveries # List delivery history
list
List all webhook subscriptions for the project. This is the default action when no ID or action flag is given.
xeroctl webhooks
xeroctl webhooks --limit 50
xeroctl webhooks --after whk_abc123
Options
| Option | Description |
|---|---|
--limit <n> |
Maximum number of results |
--after <cursor> |
Pagination cursor: ID to start after |
Output columns: ID, URL, EVENTS, ACTIVE, CREATED.
get
Show details of a specific webhook subscription. Provides URL, subscribed events, active state, creation and update timestamps, and the signing secret if one is configured.
xeroctl webhooks whk_abc123
xeroctl webhooks whk_abc123 -o json
create
Create a new webhook subscription. Both --url and --events are required. The webhook is active by default unless --inactive is specified.
# Create a webhook for model events
xeroctl webhooks --create \
--url https://example.com/hooks/xerotier \
--events model.ready,model.error
# Create with a signing secret and set to inactive
xeroctl webhooks --create \
--url https://example.com/hooks/xerotier \
--events endpoint.error,model.ready \
--secret my-signing-secret \
--inactive
Options
| Option | Description |
|---|---|
--url <url> |
Webhook delivery URL (required) |
--events <events> |
Comma-separated event types to subscribe to (required) |
--secret <secret> |
Signing secret for payload verification (optional) |
--active |
Set webhook to active state (default) |
--inactive |
Create webhook in inactive state |
Secrets: If a signing secret is configured, each delivery includes an X-Xerotier-Signature header you can use to verify the payload authenticity.
update
Update an existing webhook. All fields are optional -- only the provided fields are changed.
# Update the URL
xeroctl webhooks whk_abc123 --update --url https://new.example.com/hook
# Change subscribed events
xeroctl webhooks whk_abc123 --update --events model.ready,endpoint.error,model.deleted
# Activate or deactivate
xeroctl webhooks whk_abc123 --update --active
xeroctl webhooks whk_abc123 --update --inactive
# Rotate the signing secret
xeroctl webhooks whk_abc123 --update --secret new-signing-secret
Options
| Option | Description |
|---|---|
--url <url> |
New webhook delivery URL |
--events <events> |
Comma-separated replacement event type list |
--secret <secret> |
New signing secret |
--active |
Set webhook to active |
--inactive |
Set webhook to inactive |
Mutually exclusive: --active and --inactive cannot be used together.
delete
Delete a webhook subscription. A confirmation prompt is shown by default.
# With confirmation prompt
xeroctl webhooks whk_abc123 --delete
# Skip confirmation
xeroctl webhooks whk_abc123 --delete --force
# Dry run
xeroctl webhooks whk_abc123 --delete --dry-run
Options
| Option | Description |
|---|---|
--force |
Skip the confirmation prompt |
--dry-run |
Show what would be deleted without making changes |
test
Send a test event to the webhook endpoint. Useful for verifying connectivity and payload handling before relying on live events.
xeroctl webhooks whk_abc123 --test
On success, the command prints the HTTP status code returned by your endpoint and the delivery ID. On failure, an error message is displayed.
Dry run: Passing --dry-run will show what would happen without sending the test event.
deliveries
List the delivery history for a webhook. Shows each delivery attempt with event type, HTTP status code, success status, and timestamp.
xeroctl webhooks whk_abc123 --deliveries
xeroctl webhooks whk_abc123 --deliveries --limit 50
xeroctl webhooks whk_abc123 --deliveries --after del_xyz
Options
| Option | Description |
|---|---|
--limit <n> |
Maximum number of delivery records to return |
--after <cursor> |
Pagination cursor: delivery ID to start after |
Output columns: ID, EVENT_TYPE, STATUS (HTTP code), SUCCESS, CREATED.
Event Types
Pass event type names as a comma-separated string to --events. Common event types include:
| Event Type | Description |
|---|---|
model.ready |
A model has finished syncing and is ready for inference |
model.error |
A model encountered an error during sync or validation |
model.deleted |
A model was deleted from the project |
endpoint.error |
An endpoint reported an error condition |
Examples
Create and Verify a Webhook
# Create
xeroctl webhooks --create \
--url https://hooks.example.com/xerotier \
--events model.ready,model.error \
--secret "my-secret-token"
# Verify the test event is delivered
xeroctl webhooks whk_abc123 --test
# Review delivery log
xeroctl webhooks whk_abc123 --deliveries
Temporarily Disable a Webhook
xeroctl webhooks whk_abc123 --update --inactive
# Re-enable later
xeroctl webhooks whk_abc123 --update --active
List and Clean Up
# List all webhooks
xeroctl webhooks
# Get details of a specific webhook
xeroctl webhooks whk_abc123
# Delete unused webhook
xeroctl webhooks whk_abc123 --delete --force
