Home / Guides / Quickstart
Quickstart: zero to first verified action
This guide takes you through the full execution chain — propose, authorize, execute, verify — using the governed-webhook reference implementation. No accounts, no API keys, no network beyond your own machine.
Prerequisites: Node.js 20+ and curl. About 15 minutes.
On this page
1. Understand the chain
Read the execution-chain spec once, end to end. The mental model you need: a webhook arrives (an event), it is validated against a contract (stage 1), scoped to a tenant (stage 2), attributed to an actor (stage 3), decided by deterministic policy (stage 4), executed in a governed transaction (stage 5), and recorded as a hash-chained receipt (stage 6).
2. Get the reference implementation
Copy the code from the governed-webhook reference into a working directory. It is a single file, governed-webhook.js, with no dependencies beyond the Node.js standard library.
mkdir ametios-quickstart && cd ametios-quickstart
# paste governed-webhook.js from the reference implementation into this directory
node --check governed-webhook.js && echo "syntax OK"
3. Start the local receiver
The reference implementation starts an HTTP server on localhost:8787 with an embedded policy bundle and a fixed signing secret for local use.
node governed-webhook.js
# listening on http://localhost:8787
4. Send a signed webhook
The receiver requires an HMAC-SHA256 signature over the raw request body, sent as X-Signature. The local secret is local-dev-secret (hardcoded in the reference for local runs only — never use it anywhere else).
BODY='{"event":"invoice.paid","customer_id":"cus_88412","amount_cents":45000}'
SIG=$(printf '%s' "$BODY" | openssl dgst -sha256 -hmac "local-dev-secret" | awk '{print $2}')
curl -s -X POST http://localhost:8787/webhook \
-H "Content-Type: application/json" \
-H "X-Signature: $SIG" \
-d "$BODY" | head -c 600; echo
You should get a 200 response containing an action_id and a receipt. If the signature is wrong or the policy denies the event, you get a 401 or 403 with a typed error — try sending without the X-Signature header to see stage 1/3 rejection in action.
5. Inspect the evidence receipt
The response embeds the full evidence receipt: tenant scope, actor, policy bundle version, decision, evaluation trace, and the receipt hash chain link. Compare it field-by-field with the evidence model's recorded fields. Then trigger a denied event — for example {"event":"refund.requested","amount_cents":500000} — and observe the decision: "deny" receipt with a null outputs_hash.
6. Verify the receipt
Copy the code from the evidence-receipt reference into evidence-receipt.js in the same directory. Then save the receipt JSON from the webhook response into receipt.json and verify it: canonicalize, hash, compare. Verification needs no server — only the receipt and the spec.
# save the receipt object from the webhook response into receipt.json
node -e '
const { verifyReceipt } = require("./evidence-receipt.js");
const receipt = require("./receipt.json");
console.log("receipt valid:", verifyReceipt(receipt));
'
Next steps
- Policy model — write your own rules for the webhook's policy bundle.
- Module build guide — package what you built as an AmetiOS module.
- Approval-inbox reference — handle
require-approvaldecisions with a human gate.