Decisions and Outcomes
Understand terminal Action states, version-bound decisions, signed receipts, and reported execution outcomes.
An Action begins in open state and can become resolved, cancelled, or expired. Terminal state is immutable.
Ordinary Actions use /decision. An Action with an Approval Policy uses /votes; the Action stays open until its threshold is met or any named reviewer rejects it.
Version and fingerprint binding
Material changes advance action_version and change the canonical fingerprint. High-risk clients should send both values when resolving so a stale review fails closed.
Newly resolved Actions include a compact Ed25519-signed receipt bound to the Action ID, version, fingerprint, response, and resolution metadata. Fetch trusted public keys from:
https://api.actionbox.cloud/.well-known/actionbox-receipt-keys.jsonOlder terminal rows created before receipt support may not contain a receipt.
Execution outcomes
A human decision records authorization; it does not prove the software operation succeeded. After executing an approved operation, report one outcome for the exact resolved Action snapshot.
outcome = resolved.report_outcome(
"success",
duration_ms=48_312,
rollback=False,
)Exact retries are idempotent. A conflicting second outcome is rejected.
Reading the Action event history
The Action detail response includes up to the 100 most recent events in chronological order. event_count reports the retained total, and events_truncated tells you when the response is a recent window. Each event has an id, type, actor_type, actor_id, payload, and created_at. The account export retains the complete event history covered by the workspace's retention policy. The web and mobile apps turn the recent records into the audit trail shown to reviewers.
Creation and review events:
| Event type | What it records |
|---|---|
created | The Source created the Action. |
updated | The Source changed the open Action. The payload identifies the changed fields and current version. |
snoozed | A reviewer hid the Action until the recorded time. |
unsnoozed | ActionBox returned a due Action to the inbox. |
assigned | A workspace member assigned the Action to someone. |
unassigned | A workspace member removed the current assignment. |
claimed | A workspace member assigned the Action to themselves. |
context_requested | A reviewer asked the Source for specific information. |
context_provided | The Source updated the same Action with the requested context. |
context_unavailable | The Source could not provide the request and supplied a reason. The Action stays open. |
Notification events:
| Event type | What it records |
|---|---|
notification_sent | ActionBox sent an Action notification. |
notification_cancelled | A scheduled notification was cancelled before delivery. |
reminder_sent | ActionBox sent a reminder for an open Action. |
escalated | ActionBox sent the configured escalation for an open Action. |
Decision and execution events:
| Event type | What it records |
|---|---|
resolved | A reviewer or Source recorded the terminal response. |
approval_recorded | A named reviewer cast an immutable vote for the current Action version. |
approvals_invalidated | A material change made earlier votes historical and required fresh review. |
approval_overridden | The Source used an override that the immutable policy explicitly allowed. |
cancelled | The Source cancelled the Action. |
expired | The Action reached its expiry rule without a normal reviewer response. |
outcome_reported | The Source reported whether the operation authorized by the decision succeeded or failed. |
Action Control events:
| Event type | What it records |
|---|---|
control_requested | A reviewer invoked an Action Control. |
control_delivered | The callback request reached the Source. |
control_delivery_failed | ActionBox exhausted delivery attempts before the Source accepted the callback. |
control_running | The Source reported that the requested operation started. |
control_succeeded | The Source reported that the requested operation succeeded. |
control_failed | The Source reported that the requested operation failed. |
control_verified | A linked Watch or Agent Run independently observed recovery after the operation. |
control_cancelled | ActionBox cancelled pending control work because the Action changed or closed. |
control_expired | The control request reached its deadline without a terminal result. |
Treat events as an audit history, not as the current state. Read status, response, context_request, and control request records for the latest state. Event payloads are additive, so clients should ignore fields they do not recognize.
Webhook authenticity
Webhook transport uses a separate per-Source HMAC secret. Verify the exact raw callback body and timestamp as described in Webhooks and callbacks. Do not confuse the HMAC delivery signature with the offline-verifiable Ed25519 decision receipt.