Event Chains
An Event Chain is a tamper-evident, append-only log for agent jobs where each record links to the previous record by hash and is optionally signed. Use it to make webhook and changefeed driven automation auditable, idempotent, and fail-closed when policy or identity does not validate.
OpenClaw is the baseline agent runtime, but prompts alone cannot safely constrain execution. You need permissioned execution under policy-as-code so the runtime can block side effects when the Work Policy Contract (WPC) or CST does not match the job.
Step-by-step runbook
-
Define your WPC as the machine-readable “what is allowed” contract for this automation. Store it in the WPC registry and treat the resulting policy hash as the stable identifier your workers must pin to.
-
Issue a CST for the specific job and pin it to the WPC hash (optional policy hash pinning). Use job-scoped CST binding to reduce replay across jobs.
-
Secure inbound webhooks and changefeeds before they touch the agent. For Microsoft-style eventing, use Microsoft Entra ID protected endpoints and validate the caller identity and audience; otherwise validate vendor signatures or shared-secret HMAC via official API guidance.
-
Write an Event Chain record as your first step after accepting an inbound delivery, before doing any side effects. Make the record include a deterministic idempotency key derived from the vendor event id, subject, and resource version.
-
Run the agent in OpenClaw with explicit tool policy and sandbox settings, then route model calls through clawproxy to obtain gateway receipts. If you use OpenRouter via fal, keep it routed through clawproxy so receipts cover model traffic.
-
For each state transition (validated, planned, executed, acknowledged), append an event with a hash pointer to the previous event. On completion, produce a proof bundle that includes gateway receipts plus the Event Chain head hash and critical metadata for verification.
Threat model
Event Chains are mainly about controlling side effects under unreliable delivery and hostile inputs. They complement OpenClaw’s local sandbox and tool policy boundary by adding verifiable, job-scoped history that you can check before executing and after incidents.
| Threat | What happens | Control |
|---|---|---|
| Webhook replay or duplicate delivery | The same vendor event is delivered multiple times, potentially causing repeated writes, repeated approvals, or repeated outbound messages. | Derive an idempotency key and record it in the Event Chain; refuse to execute side effects if the key already exists for the same WPC hash and job-scoped CST binding. |
| Forged webhook sender | An attacker posts a lookalike payload to your endpoint to trick the agent into acting. | Authenticate delivery (for example, Microsoft Entra ID for Event Grid webhook delivery) and record the verified caller identity claims in the chain before any tool execution. |
| Prompt injection via event payload | Untrusted event fields include instructions that cause the agent to call tools outside intent. | Do not rely on prompt rules alone; enforce policy-as-code through WPC-derived tool allow/deny and OpenClaw sandboxing. Store the normalized “facts extracted” as a separate chain event so auditors can see what the agent actually used. |
| Policy drift during execution | A long-running job starts under one policy and finishes under a different one, making authorization ambiguous. | Pin to a WPC hash at job start and include it in every event record; optionally require the CST to carry the pinned policy hash and fail closed if it does not match. |
| Log tampering after incident | Someone modifies stored logs to hide a bad tool call or to alter who approved what. | Hash-chain the records and optionally sign chain heads; keep the chain head hash inside the proof bundle alongside gateway receipts so verification detects edits. |
| Infinite loops in event-driven remediation | Your handler changes a resource, which triggers another event, which triggers another change. | Include “reason” and “causal parent” fields, plus a loop guard counter in the chain; filter on specific event types and subjects so the handler does not re-trigger itself. |
Policy-as-code example
This is a minimal, schema-style example showing how to bind a job to a WPC and require deterministic idempotency. Treat it as a template for your own policy artifact, not a fixed API contract.
{
"kind": "event_chain_policy",
"wpc_policy_hash_b64u": "pinned_policy_hash_here",
"cst": {
"require_job_scoped_binding": true,
"require_scope_hash_match": true,
"optional_policy_hash_pinning": true
},
"ingress": {
"webhook_auth": {
"mode": "entra_id_or_vendor_signature",
"expected_audience": "your_endpoint_audience",
"require_tls": true
},
"idempotency": {
"key_fields": ["vendor_event_id", "subject", "resource_version"],
"reject_duplicates": true
}
},
"event_chain": {
"hash_alg": "sha256",
"require_prev_hash": true,
"sign_chain_head": "optional",
"required_events": ["received", "authenticated", "validated", "planned", "executed", "acknowledged"],
"fail_closed_on_validation_error": true
},
"execution": {
"openclaw": {
"sandbox_mode": "all",
"tools_profile": "allowlist_only",
"deny_elevated_by_default": true
},
"model_calls": {
"require_clawproxy_gateway_receipts": true
}
}
}
Validation rules should be deterministic and fail-closed. If the chain breaks, the WPC hash is missing, the CST scope hash does not match, or webhook authentication fails, the worker must not execute tools and must not call models through clawproxy.
For changefeeds and webhooks, validate before parsing into agent instructions. Store both the raw payload hash and a normalized view so you can later show exactly what changed without re-parsing untrusted input.
What proof do you get?
You get gateway receipts for model calls emitted by clawproxy, suitable for verifying what model was called and with what request boundaries. You also get a proof bundle that can include those receipts plus job metadata and pointers to your Event Chain head hash for end-to-end audit and verification.
If you publish artifacts for review, a Trust Pulse can store and display the proof bundle for auditors. This is most useful when your incident process needs a single object to attach to tickets and postmortems.
For idempotency disputes, the Event Chain provides a replayable narrative: the inbound delivery identity, the idempotency decision, the policy hash in force, and the execution milestones. Verification checks should reject any bundle whose receipt signatures do not validate or whose chain head hash does not match the chain content you stored.
Rollback posture
Rollback is about stopping further side effects and proving what already happened. Your posture should rely on CST revocation, policy hash pinning, and tool sandbox boundaries, then use the Event Chain plus proof bundle to drive a precise cleanup.
| Action | Safe rollback | Evidence |
|---|---|---|
| Webhook handler deployed with wrong mapping | Revoke or expire the CSTs issued for that job class and block new job creation until WPC is corrected. Re-run only from a known chain event id, not “latest.” | Event Chain shows which payloads were accepted and which actions were executed; proof bundle anchors model-call receipts that influenced decisions. |
| Duplicate delivery caused repeated write | Stop processing when the idempotency key is seen again and mark the duplicate as “ignored.” Apply compensating actions only once, tied to the first executed event id. | Chain contains the idempotency key, first execution event, and later duplicate receipt; auditors can see deterministic duplicate suppression. |
| Policy changed mid-run | Require that every tool call checks the pinned WPC hash; if mismatch, stop and require a new job under a new CST. Do not “continue under new policy” automatically. | Each chain event repeats the WPC hash; mismatches show where execution halted, with corresponding receipts for any completed model calls. |
| Prompt injection suspected | Quarantine the job, rotate any exposed secrets outside this layer, and re-run with stricter OpenClaw tool allowlists and sandboxing. If needed, implement egress allowlists enforced outside clawproxy (optional) to limit exfil paths. | Event Chain captures the untrusted input hash and the extracted facts; gateway receipts show model prompts and responses at the boundary. |
FAQ
How is an Event Chain different from normal application logs?
Normal logs are easy to edit and hard to validate, especially after an incident. An Event Chain is append-only by construction, with hash links that make deletions and rewrites detectable.
Why not handle idempotency only in the webhook handler database?
You still should, but the agent execution layer needs to enforce it too. Putting the idempotency decision inside the Event Chain means every subsequent step can fail closed before tools run, even if the upstream handler is buggy.
Why is permissioned execution (policy-as-code) required instead of prompt-only rules?
Prompt-only rules are advisory and can be bypassed by ambiguous inputs or model behavior. A WPC plus CST constraints let the runtime block tool calls and model calls when identity, scope hash, or policy hash does not validate.
Do I need Microsoft Entra ID to secure my webhooks?
No, but you need strong sender authentication appropriate to the vendor. If you are using Azure Event Grid, Microsoft documents securing webhook delivery with Microsoft Entra ID; otherwise follow the vendor’s official API signing guidance and record the verified identity claims in the Event Chain.
What does Claw EA verify automatically versus what we must implement?
Shipped primitives cover WPC registry fetch and verify, CST issuance and scope hash, gateway receipts from clawproxy, and proof bundles with job-scoped CST binding. An Event Chain is a recommended policy artifact format you can implement in your worker and then anchor into the proof bundle; end-to-end wiring can be done via enterprise buildout.