Home / Guides / Quickstart

Quickstart: zero to first verified action

Draft Everything below runs locally on your machine. A hosted sandbox is Roadmap.

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.

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.

Illustrative referenceSet up a working directory.
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.

Illustrative referenceStart the receiver.
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).

Illustrative referenceSend a signed test webhook.
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.

Illustrative referenceVerify a saved receipt.
# 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