Webhook Events
Every execution lifecycle event the router fans out over the exec.* namespace. Same envelope, same HMAC-SHA256 signing, same retry schedule as the rest of the webhook surface. Subscribe with the standard create endpoint, verify the signature, dedupe on event id.
// nav: g e envelope · g x execution · g a approvals · g s signing · g d delivery · ? chip
Overview
Snake_case on the wire. All
exec.* payload field names are emitted in
snake_case (for example invocation_id,
tool_name, workspace_id). The JSON
examples below show the exact field names that subscribers
will receive.
| Event | Status | Description |
|---|---|---|
exec.dispatched | reserved | Reserved event type; no payload is emitted at this time. |
exec.completed | reserved | Reserved event type; no payload is emitted at this time. |
exec.failed | active | A run the router could not finish after a restart or a lost Erebine Execution Manager (EEM) was marked failed. |
exec.timeout | reserved | Reserved event type; no payload is emitted at this time. |
exec.cancelled | active | A waiting or running call was cancelled. |
exec.ambiguous | reserved | Reserved event type; no payload is emitted at this time. |
exec.approval_requested | active | A tool call started waiting for approval. |
exec.approved | active | A waiting call was approved. |
exec.rejected | active | A waiting call was rejected. |
exec.approval_escalated | active | A destructive or irreversible call reached its deadline and escalated to owners. |
exec.approval_timed_out | active | A waiting call timed out without a decision. |
exec.agent_enrolled | active | An EEM completed enrollment. |
exec.agent_offline | active | An EEM reported a run the router has no record of. |
exec.discovery_pending | reserved | Reserved event type; no payload is emitted at this time. |
exec.workspace_created | reserved | Reserved event type; no payload is emitted at this time. |
exec.workspace_budget_exhausted | reserved | Reserved event type; no payload is emitted at this time. |
Event types marked reserved are declared in the router enum but no payload is currently produced. Subscribers may register for them without error, but no deliveries will fire until the router begins emitting them.
Event Envelope
Every exec.* delivery uses the canonical webhook
envelope. The data object varies by event type and
is documented per-event below.
{
"id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
"object": "event",
"type": "exec.approval_requested",
"created_at": 1709000100,
"data": { }
}
| Field | Type | Description |
|---|---|---|
id | string | Unique event identifier prefixed with evt_ (24 hex characters). Suitable for deduplication. |
object | string | Always the literal string event. |
type | string | Event type identifier (for example exec.approved). |
created_at | integer | Unix timestamp (seconds since epoch) when the event was emitted. |
data | object | Event-specific payload. Schema depends on type. |
The project id is not placed in the JSON body;
the owning project is the subscription's. Every data
value is a string.
End-to-End Wire Example
The following is a complete exec.approval_requested
delivery exactly as a subscriber endpoint will receive it.
POST /erebine HTTP/1.1
Host: ops-ingest.example.com
Content-Type: application/json
User-Agent: Erebine-Webhooks/1.0
X-Webhook-ID: 0f8c4a1e-1c2d-4a9b-9c1f-2e3d4a5b6c7d
X-Webhook-Timestamp: 1709000100
X-Webhook-Signature: sha256=9c1a...e3f0
{
"id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2",
"object": "event",
"type": "exec.approval_requested",
"created_at": 1709000100,
"data": {
"invocation_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"approval_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"tool_name": "k8s_drain_node",
"risk": "destructive",
"workspace_id": "5b2a9c7e-6d1f-4a38-9e05-c4f8a1b2d3e6",
"requested_at": "2026-04-13T14:58:00Z",
"deadline_at": "2026-04-13T15:13:00Z",
"url": "https://app.example.com/ops?invocation=8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52"
}
}
Execution Events
Each execution lifecycle event has its own payload schema. The field set is intentionally minimal; richer state is fetched on demand via the invocation read endpoint.
exec.dispatched
Reserved event type; no payload is emitted at this time.
exec.completed
Reserved event type; no payload is emitted at this time.
exec.failed
Fires when the router marks a run failed because a restart or a lost EEM left it unfinished.
{
"invocation_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52",
"error_code": "failed_router_restart",
"error_message": "Router restart could not reclaim the invocation",
"failed_at": "2026-04-13T14:58:48.612Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | Unique invocation identifier. |
error_code | string | failed_router_restart or heartbeat_budget_exhausted. |
error_message | string | Human-readable error description. |
failed_at | string | ISO 8601 timestamp when the failure was recorded. |
exec.timeout
Reserved event type; no payload is emitted at this time.
exec.cancelled
{
"invocation_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"reason": "user_requested",
"cancelled_at": "2026-04-13T14:59:12Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | The cancelled call. |
reason | string | Why it was cancelled: user_requested. |
cancelled_at | string | ISO 8601 timestamp when the cancel was recorded. |
Approval Events
Approval events fire as a waiting call is requested, decided,
escalated or timed out. Each event carries only the fields
relevant to its stage. approval_id equals
invocation_id.
exec.approval_requested
{
"invocation_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"approval_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"tool_name": "k8s_drain_node",
"risk": "destructive",
"workspace_id": "5b2a9c7e-6d1f-4a38-9e05-c4f8a1b2d3e6",
"requested_at": "2026-04-13T14:58:00Z",
"deadline_at": "2026-04-13T15:13:00Z",
"url": "https://app.example.com/ops?invocation=8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | The waiting call. |
approval_id | string | The approval to decide; the same value as invocation_id. |
tool_name | string | Tool the call runs. |
risk | string | Risk level declared by the tool manifest. |
workspace_id | string | Workspace the call targets. Absent when the call has none. |
requested_at | string | ISO 8601 timestamp when the call started waiting. |
deadline_at | string | ISO 8601 timestamp when the call times out. Absent when it never does. |
url | string | The Operations page link that opens this call's decision. Absent when the deployment has no public address. |
exec.approved
{
"invocation_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"approval_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"decided_by": "c7a4e2d9-3f15-4b8a-9d60-2e1b5f7c8a03",
"approved_at": "2026-04-13T14:59:12Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | Call released to run. |
approval_id | string | Approval that was granted. |
decided_by | string | User id of the approver; empty when no person is known. |
approved_at | string | ISO 8601 timestamp when the decision was recorded. |
exec.rejected
{
"invocation_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"approval_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52",
"reason": "out of change window",
"rejected_at": "2026-04-13T14:59:12Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | Call that will not run. |
approval_id | string | Approval that was rejected. |
reason | string | The decider's reason; empty when none was given. |
rejected_at | string | ISO 8601 timestamp when the rejection was recorded. |
exec.approval_escalated
{
"invocation_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52",
"approval_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52",
"stage": "0",
"target": "role:owner",
"target_kind": "role",
"target_value": "owner",
"escalated_at": "2026-04-13T15:13:00Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | Call that escalated. |
approval_id | string | Approval that escalated. |
stage | string | Index of the escalation stage, starting at 0. |
target | string | target_kind and target_value joined by a colon. |
target_kind | string | Who the call escalated to: role. |
target_value | string | The role: owner. |
escalated_at | string | ISO 8601 timestamp when the escalation fired. |
exec.approval_timed_out
{
"invocation_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52",
"approval_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52",
"timed_out_at": "2026-04-13T15:13:02Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | Call that timed out and will not run. |
approval_id | string | Approval that expired without a decision. |
timed_out_at | string | ISO 8601 timestamp when the timeout was recorded. |
Ids are UUIDs. Compare them case-insensitively: the escalation and timeout events carry them in upper case.
The exec.approval_requested event is the trigger
for approval-delegation patterns (forwarding to Slack,
PagerDuty, or an internal approval system). Any downstream
system that re-emits the payload must verify
the original X-Webhook-Signature before trusting
its contents; see Signature
Verification.
EEM Events
exec.agent_enrolled
{
"worker_id": "3f9c1d2b-8a04-4c1e-9b6f-0d2e7a1c5b90",
"project_id": "A1B2C3D4-E5F6-4789-8ABC-DEF012345678",
"region": "us-east",
"agent_role": "execution",
"registration_name": "fleet-ops-sfo1"
}
| Field | Type | Description |
|---|---|---|
worker_id | string | Id the router assigned to the EEM. |
project_id | string | UUID of the project that owns the EEM. |
region | string | Region the EEM declared. |
agent_role | string | Always execution for this event. |
registration_name | string | Name the EEM registered under. Absent when it declared none. |
exec.agent_offline
Fires when an EEM reports a run the router has no record of.
{
"invocation_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52",
"agent_id": "3f9c1d2b-8a04-4c1e-9b6f-0d2e7a1c5b90",
"reason": "orphan_execution",
"detected_at": "2026-04-13T15:00:12.000Z"
}
| Field | Type | Description |
|---|---|---|
invocation_id | string | The run the EEM reported. |
agent_id | string | EEM that reported it. |
reason | string | orphan_execution. |
detected_at | string | ISO 8601 timestamp when the report was recorded. |
Workspace Events
exec.workspace_created and
exec.workspace_budget_exhausted are declared in the
router event-type enum but are not currently emitted. The
payload schema is reserved and will be documented here when the
router begins producing these events. Subscribers may register
for them today; no deliveries will fire until the emitter ships.
Discovery Events
exec.discovery_pending is declared in the router
event-type enum but is not currently emitted. The payload
schema is reserved and will be documented here when the router
begins producing this event.
Subscribing to Events
Webhook endpoints are created with the standard
POST /v1/webhooks request shape. The
events array selects which event types are
delivered; there is no per-endpoint workspace or risk filter
today, so subscribers receive every delivery for the event
types they list.
{
"url": "https://ops-ingest.example.com/erebine",
"events": ["exec.approval_requested", "exec.approval_escalated"],
"description": "On-call approval bridge",
"metadata": { "owner": "platform-oncall" }
}
For finer-grained routing, inspect
data.workspace_id and data.risk
on receipt and drop or re-route downstream. See the
Webhooks API reference for
the complete create, update, list, and delete surface.
Signature Verification
Every delivery includes three HTTP headers that let subscribers authenticate the payload:
| Header | Description |
|---|---|
X-Webhook-ID | UUID of the webhook subscription the delivery is for. |
X-Webhook-Timestamp | Unix epoch (seconds) when the router signed the request. |
X-Webhook-Signature | HMAC-SHA256 signature in the format sha256=<hex-digest>. |
The signature is computed as
HMAC_SHA256(secret, timestamp + "." + raw_body),
hex-encoded and prefixed with sha256=. The
secret is returned exactly once at endpoint create
time. See the Webhooks API reference
for verification snippets in Python, Node, and shell.
Delivery & Retry
- Deliveries retry on non-2xx responses or network errors using a fixed exponential backoff schedule: 1 min, 5 min, 15 min, 1 hr, 4 hr. A delivery is attempted up to 6 times total (1 initial attempt plus up to 5 retries).
- Per-attempt delivery timeout is 30 seconds; endpoints that exceed this are treated as a failed attempt and re-scheduled per the backoff above.
- Ordering is not guaranteed. Subscribers
should dedupe on the envelope
idand sort bycreated_at. - At-least-once delivery. The envelope
idis suitable as a dedup key. - Delivery records (request payload, response status, response
body up to 1 KiB) surface in
GET /v1/webhooks/:id/deliveries.
For the full retry table, signing math, and limits, see the Webhooks API reference.