docs
// Tools

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: POST over HTTPS with a JSON body. 2xx within 10 s counts as success.
  • Signature: HMAC-SHA256(secret, timestamp + "." + body), hex-encoded, sent as X-Webhook-Signature.
  • Replay defence: subscribers must reject deliveries with X-Webhook-Timestamp older than five minutes.
  • Retry policy: exponential backoff up to six attempts, terminal state exhausted; visible via --deliveries.
  • Test rate: --test is 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

bash
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.

bash
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.

bash
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.

bash
# 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.

bash
# 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.

bash
# 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.

bash
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.

bash
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 TypeDescription
batch.completedA batch job completed successfully.
batch.failedA batch job failed.
batch.cancelledA batch job was cancelled.

Response (2)

Event TypeDescription
response.completedA response completed successfully.
response.failedA response failed.

File (2)

Event TypeDescription
file.uploadedA file was uploaded.
file.deletedA file was deleted.

Conversation (2)

Event TypeDescription
conversation.createdA conversation was created.
conversation.deletedA conversation was deleted.

Exec / EEM (16)

Event TypeDescription
exec.dispatchedAn EEM tool invocation was dispatched to an EEM.
exec.completedAn EEM tool invocation completed successfully.
exec.failedAn EEM tool invocation failed (non-zero exit or transport error).
exec.timeoutAn EEM tool invocation exceeded its declared timeout.
exec.ambiguousAn EEM invocation target was ambiguous and needs operator resolution.
exec.approval_requestedAn approval request was enqueued for a destructive invocation.
exec.approvedAn approval request was approved.
exec.rejectedAn approval request was explicitly rejected.
exec.cancelledA waiting or running EEM invocation was cancelled by its requester or a manager.
exec.approval_escalatedAn approval request was escalated to the next contact.
exec.approval_timed_outAn approval request timed out without a decision.
exec.agent_enrolledAn EEM completed enrollment.
exec.agent_offlineAn EEM transitioned to offline.
exec.discovery_pendingAn EEM discovery request is awaiting operator action.
exec.workspace_createdAn operational workspace was created.
exec.workspace_budget_exhaustedA 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 TypeDescription
agent.createdAn EIM or EEM record was created via the management API.
agent.updatedAn EIM or EEM record was updated via the management API.
agent.deletedAn EIM or EEM was soft-deleted via the management API.
agent.enrolledAn EIM or EEM finished enrollment and is eligible for dispatches.
agent.key_rotatedAn EEM's CURVE transport keypair rotated.

Join Key (2)

Event TypeDescription
join_key.createdA new join key was minted via the management API.
join_key.revokedA 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 TypeDescription
scheduled_task.run_completedA scheduled task's run ended completed.
scheduled_task.run_failedA scheduled task's run ended failed, with its error code.
scheduled_task.pausedA scheduled task stopped itself: paused for a reason other than a person, or failed.

Observability (2)

Event TypeDescription
ox.alert.raisedA learning invariant was violated (raised at critical severity).
ox.learning.clusterA 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

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

bash
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

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