erectl webhooks
Subscribe an HTTPS endpoint to project events, fire a test delivery, and audit the delivery log.
Signing secret is returned exactly once at create. Thirty-seven event types across nine families: batch, response, file, conversation, exec, agent, join_key, scheduled_task, ox.
Overview
- Delivery:
POSTover HTTPS with a JSON body.2xxwithin 10 s counts as success. - Signature:
HMAC-SHA256(secret, timestamp + "." + body), hex-encoded, sent asX-Webhook-Signature. - Replay defence: subscribers must reject deliveries with
X-Webhook-Timestampolder than five minutes. - Retry policy: exponential backoff up to six attempts, terminal state
exhausted; visible via--deliveries. - Test rate:
--testis capped at 10 invocations per hour per webhook.
The webhooks command uses one positional ID plus one action flag
(--create, --update, --delete,
--test, --deliveries). Action flags are mutually
exclusive; omit them all and the command lists.
Usage Pattern
erectl webhooks # List all webhooks
erectl webhooks <uuid> # Show webhook details
erectl webhooks --create --url <url> --events <e> # Create a webhook
erectl webhooks <uuid> --update --url <url> # Update a webhook
erectl webhooks <uuid> --delete # Delete a webhook
erectl webhooks <uuid> --test # Send a test event
erectl webhooks <uuid> --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.
erectl webhooks
erectl webhooks --limit 50
erectl webhooks --after 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10
Options
| Option | Description |
|---|---|
--limit <n> |
Maximum number of results (default 20, server cap 100) |
--after <cursor> |
Pagination cursor: webhook UUID to start after |
Output columns: ID, URL, EVENTS, ACTIVE, CREATED. Webhook IDs are bare UUIDs (no whk_ prefix).
get
Show details of a specific webhook subscription. Provides URL, subscribed events, active state, and creation and update timestamps. The signing secret is not displayed here: it is returned exactly once in the create response and never re-exposed. If you lost it, delete the webhook and create a new one.
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 -o json
create
Create a new webhook subscription. Both --url and --events are required. A new webhook starts active; pass --inactive to create it paused, and resume it later with --update --active. The signing secret is printed even with --quiet, and -o json prints the API response with the secret under secret.
# Create a webhook for batch events
erectl webhooks --create \
--url https://example.com/hooks/erebine \
--events batch.completed,batch.failed
# Create it paused: no deliveries until --update --active
erectl webhooks --create \
--url https://example.com/hooks/erebine \
--events batch.completed \
--inactive
# Dry-run (validate without creating)
erectl webhooks --create \
--url https://example.com/hooks/erebine \
--events agent.enrolled \
--dry-run
Options
| Option | Description |
|---|---|
--url <url> |
Webhook delivery URL (required) |
--events <events> |
Comma-separated event types to subscribe to (required) |
--active / --inactive |
Start the webhook active (the default) or paused. Mutually exclusive. |
--dry-run |
Validate inputs and show what would be created without persisting |
Signing secret: The server auto-generates a 32-byte hex signing secret when the webhook is created and returns it exactly once in the create response. Store it immediately; subsequent erectl webhooks <id> calls will not display it. The signing secret cannot be supplied or rotated; to change it, delete the webhook and create a new one.
Delivery Headers
Every delivery carries three vendor headers in addition to Content-Type: application/json. Subscribers verify by recomputing the HMAC and comparing in constant time.
| Header | Value |
|---|---|
X-Webhook-ID |
UUID of the delivery attempt (not the webhook). Use as an idempotency key. |
X-Webhook-Timestamp |
Unix epoch seconds at signing time. Reject deliveries older than five minutes. |
X-Webhook-Signature |
HMAC-SHA256(secret, timestamp + "." + raw_body), hex-encoded. |
Payload envelope (id, object, type, created_at, data) and verification snippets in Python, Node, and Swift are documented in the Webhooks API reference.
update
Update an existing webhook. All fields are optional, only the provided fields are changed.
# Update the URL
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --url https://new.example.com/hook
# Change subscribed events
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --events response.completed,batch.completed,file.uploaded
# Activate or deactivate
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --active
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --inactive
# Dry-run (preview the change without persisting)
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --inactive --dry-run
Options
| Option | Description |
|---|---|
--url <url> |
New webhook delivery URL |
--events <events> |
Comma-separated replacement event type list |
--active |
Set webhook to active |
--inactive |
Set webhook to inactive |
--dry-run |
Show what would change without persisting the update |
State flag conflict: --active and --inactive cannot be used together. (Action-flag exclusivity is covered in Overview.)
Cannot change the signing secret: Update does not accept a --secret flag and the server has no field to change the signing secret. To rotate, delete the webhook and create a new one (the create response will return the new secret exactly once).
delete
Delete a webhook subscription. A confirmation prompt is shown by default.
# With confirmation prompt
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --delete
# Skip confirmation
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --delete --force
# Dry run
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --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.
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --test
The command prints the HTTP status code your endpoint returned, and the error when the delivery failed. On failure, an error message is displayed.
Dry run: Passing --dry-run will show what would happen without sending the test event.
Rate limit: The test endpoint is rate-limited to 10 invocations per hour per webhook.
deliveries
List the delivery history for a webhook. Shows each delivery with its event type, delivery state, HTTP status code, and timestamp.
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --deliveries
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --deliveries --limit 50
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --deliveries --after 7b2d4c1a-9e3f-4a8b-bc56-1f0e8d3a4b2c
Options
| Option | Description |
|---|---|
--limit <n> |
Maximum number of delivery records to return (default 20, server cap 100) |
--after <cursor> |
Pagination cursor: delivery UUID to start after |
Output columns: ID, EVENT_TYPE, STATUS, HTTP, CREATED. STATUS is the delivery state: pending, delivered, failed (to be retried) or exhausted (out of retries). HTTP is the status code your endpoint returned.
Event Types
Pass event type names as a comma-separated string to --events. Unknown event types are rejected by the server with a 400 error. The canonical list (grouped by family) is below.
Batch (3)
| Event Type | Description |
|---|---|
batch.completed | A batch job completed successfully. |
batch.failed | A batch job failed. |
batch.cancelled | A batch job was cancelled. |
Response (2)
| Event Type | Description |
|---|---|
response.completed | A response completed successfully. |
response.failed | A response failed. |
File (2)
| Event Type | Description |
|---|---|
file.uploaded | A file was uploaded. |
file.deleted | A file was deleted. |
Conversation (2)
| Event Type | Description |
|---|---|
conversation.created | A conversation was created. |
conversation.deleted | A conversation was deleted. |
Exec / EEM (16)
| Event Type | Description |
|---|---|
exec.dispatched | An EEM tool invocation was dispatched to an EEM. |
exec.completed | An EEM tool invocation completed successfully. |
exec.failed | An EEM tool invocation failed (non-zero exit or transport error). |
exec.timeout | An EEM tool invocation exceeded its declared timeout. |
exec.ambiguous | An EEM invocation target was ambiguous and needs operator resolution. |
exec.approval_requested | An approval request was enqueued for a destructive invocation. |
exec.approved | An approval request was approved. |
exec.rejected | An approval request was explicitly rejected. |
exec.cancelled | A waiting or running EEM invocation was cancelled by its requester or a manager. |
exec.approval_escalated | An approval request was escalated to the next contact. |
exec.approval_timed_out | An approval request timed out without a decision. |
exec.agent_enrolled | An EEM completed enrollment. |
exec.agent_offline | An EEM transitioned to offline. |
exec.discovery_pending | An EEM discovery request is awaiting operator action. |
exec.workspace_created | An operational workspace was created. |
exec.workspace_budget_exhausted | A workspace consumed its inference-token budget for the current window. |
Agent: EIMs and EEMs (5)
The agent.* types cover both kinds: an Erebine Inference Microservice (EIM) and an EEM. The names are part of the webhook contract and keep the agent prefix.
| Event Type | Description |
|---|---|
agent.created | An EIM or EEM record was created via the management API. |
agent.updated | An EIM or EEM record was updated via the management API. |
agent.deleted | An EIM or EEM was soft-deleted via the management API. |
agent.enrolled | An EIM or EEM finished enrollment and is eligible for dispatches. |
agent.key_rotated | An EEM's CURVE transport keypair rotated. |
Join Key (2)
| Event Type | Description |
|---|---|
join_key.created | A new join key was minted via the management API. |
join_key.revoked | A join key was revoked. |
Scheduled Task (3)
Sent only for a task with webhook events on. Content-free: no task name, prompt or answer. See Scheduled Tasks.
| Event Type | Description |
|---|---|
scheduled_task.run_completed | A scheduled task's run ended completed. |
scheduled_task.run_failed | A scheduled task's run ended failed, with its error code. |
scheduled_task.paused | A scheduled task stopped itself: paused for a reason other than a person, or failed. |
Observability (2)
| Event Type | Description |
|---|---|
ox.alert.raised | A learning invariant was violated (raised at critical severity). |
ox.learning.cluster | A workspace accrued a threshold of same-category failure memories; the payload carries the cluster summary and a link to the prompt editor. |
Payload envelope shape and signature verification math: see Delivery Headers on this page and the Webhooks API reference.
Examples
Create and Verify a Webhook
# Create (server returns the signing secret in the response - store it now)
erectl webhooks --create \
--url https://hooks.example.com/erebine \
--events batch.completed,response.completed
# Verify the test event is delivered (use the UUID returned by create)
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --test
# Review delivery log
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --deliveries
Temporarily Disable a Webhook
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --inactive
# Re-enable later
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --update --active
List and Clean Up
# List all webhooks
erectl webhooks
# Get details of a specific webhook
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10
# Delete unused webhook
erectl webhooks 0f3c1a8e-2d6b-4d4e-9a17-7b4c2a9d8e10 --delete --force