docs
// Execution Management (EEM)

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.

EventStatusDescription
exec.dispatchedreservedReserved event type; no payload is emitted at this time.
exec.completedreservedReserved event type; no payload is emitted at this time.
exec.failedactiveA run the router could not finish after a restart or a lost Erebine Execution Manager (EEM) was marked failed.
exec.timeoutreservedReserved event type; no payload is emitted at this time.
exec.cancelledactiveA waiting or running call was cancelled.
exec.ambiguousreservedReserved event type; no payload is emitted at this time.
exec.approval_requestedactiveA tool call started waiting for approval.
exec.approvedactiveA waiting call was approved.
exec.rejectedactiveA waiting call was rejected.
exec.approval_escalatedactiveA destructive or irreversible call reached its deadline and escalated to owners.
exec.approval_timed_outactiveA waiting call timed out without a decision.
exec.agent_enrolledactiveAn EEM completed enrollment.
exec.agent_offlineactiveAn EEM reported a run the router has no record of.
exec.discovery_pendingreservedReserved event type; no payload is emitted at this time.
exec.workspace_createdreservedReserved event type; no payload is emitted at this time.
exec.workspace_budget_exhaustedreservedReserved 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.

json
{ "id": "evt_a1b2c3d4e5f6a7b8c9d0e1f2", "object": "event", "type": "exec.approval_requested", "created_at": 1709000100, "data": { } }
FieldTypeDescription
idstringUnique event identifier prefixed with evt_ (24 hex characters). Suitable for deduplication.
objectstringAlways the literal string event.
typestringEvent type identifier (for example exec.approved).
created_atintegerUnix timestamp (seconds since epoch) when the event was emitted.
dataobjectEvent-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.

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

json
{ "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" }
FieldTypeDescription
invocation_idstringUnique invocation identifier.
error_codestringfailed_router_restart or heartbeat_budget_exhausted.
error_messagestringHuman-readable error description.
failed_atstringISO 8601 timestamp when the failure was recorded.

exec.timeout

Reserved event type; no payload is emitted at this time.

exec.cancelled

json
{ "invocation_id": "8d1e5f3a-2b7c-4e90-a6d4-1f0c9b3e7a52", "reason": "user_requested", "cancelled_at": "2026-04-13T14:59:12Z" }
FieldTypeDescription
invocation_idstringThe cancelled call.
reasonstringWhy it was cancelled: user_requested.
cancelled_atstringISO 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

json
{ "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" }
FieldTypeDescription
invocation_idstringThe waiting call.
approval_idstringThe approval to decide; the same value as invocation_id.
tool_namestringTool the call runs.
riskstringRisk level declared by the tool manifest.
workspace_idstringWorkspace the call targets. Absent when the call has none.
requested_atstringISO 8601 timestamp when the call started waiting.
deadline_atstringISO 8601 timestamp when the call times out. Absent when it never does.
urlstringThe Operations page link that opens this call's decision. Absent when the deployment has no public address.

exec.approved

json
{ "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" }
FieldTypeDescription
invocation_idstringCall released to run.
approval_idstringApproval that was granted.
decided_bystringUser id of the approver; empty when no person is known.
approved_atstringISO 8601 timestamp when the decision was recorded.

exec.rejected

json
{ "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" }
FieldTypeDescription
invocation_idstringCall that will not run.
approval_idstringApproval that was rejected.
reasonstringThe decider's reason; empty when none was given.
rejected_atstringISO 8601 timestamp when the rejection was recorded.

exec.approval_escalated

json
{ "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" }
FieldTypeDescription
invocation_idstringCall that escalated.
approval_idstringApproval that escalated.
stagestringIndex of the escalation stage, starting at 0.
targetstringtarget_kind and target_value joined by a colon.
target_kindstringWho the call escalated to: role.
target_valuestringThe role: owner.
escalated_atstringISO 8601 timestamp when the escalation fired.

exec.approval_timed_out

json
{ "invocation_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52", "approval_id": "8D1E5F3A-2B7C-4E90-A6D4-1F0C9B3E7A52", "timed_out_at": "2026-04-13T15:13:02Z" }
FieldTypeDescription
invocation_idstringCall that timed out and will not run.
approval_idstringApproval that expired without a decision.
timed_out_atstringISO 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

json
{ "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" }
FieldTypeDescription
worker_idstringId the router assigned to the EEM.
project_idstringUUID of the project that owns the EEM.
regionstringRegion the EEM declared.
agent_rolestringAlways execution for this event.
registration_namestringName 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.

json
{ "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" }
FieldTypeDescription
invocation_idstringThe run the EEM reported.
agent_idstringEEM that reported it.
reasonstringorphan_execution.
detected_atstringISO 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.

json
{ "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:

HeaderDescription
X-Webhook-IDUUID of the webhook subscription the delivery is for.
X-Webhook-TimestampUnix epoch (seconds) when the router signed the request.
X-Webhook-SignatureHMAC-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 id and sort by created_at.
  • At-least-once delivery. The envelope id is 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.