# AgentGuard gate webhook examples Two single-file handlers that put the hosted gate in front of any agent platform that can call an HTTPS URL on each tool call. No dependencies. Copy one, set `AGENTGUARD_VENDOR_KEY`, run it, point your platform's tool-call hook at `POST /gate`. - `handler.js`: Node 18 or newer, `node handler.js` - `verify-receipt.js`: Node 18 or newer, checks the receipts either handler kept against the published key - `handler.py`: Python 3.9 or newer, `python3 handler.py`. If Python reports CERTIFICATE_VERIFY_FAILED (common with python.org builds on macOS), run the Install Certificates command that ships with Python or set `SSL_CERT_FILE` to your system bundle. Without a key both run in sandbox: decisions and signed receipts are real, nothing is stored, the response says `sandbox: true`, and the signed receipt carries `tenant_id` "sandbox" and `vendor_key_id` null. ## The three shapes Event your platform sends to the handler (metadata only, never names, numbers, transcripts or card data): {"tool": "waive_fee", "arguments": {"amount_cents": 5000, "currency": "USD", "target_system": "property_management"}, "tenant_id": "acme-storage", "agent_id": "storage-bot"} For a call or a text: {"tool": "place_call", "arguments": {"recipient_ref": "rcp_7f3a9c", "recipient_tz": "America/New_York", "consent_ref": "cns_01HZX"}, "tenant_id": "acme-storage", "agent_id": "collections-bot"} What the handler answers: {"proceed": true, "text": "permitted under the policy", "receipt_id": "rcpt_...", "receipt": {...}} {"proceed": false, "approval_id": "apr_...", "status_url": "...", "text": "held for a person under the policy", "receipt_id": "rcpt_...", "receipt": {...}} {"proceed": false, "reason": "outside the calling window set in the policy", "receipt_id": "rcpt_...", "receipt": {...}} When the gate does not answer in 2 seconds, the handler reads the policy's `on_unavailable` entry for that action type (`proceed` or `stop`, default `stop`), answers accordingly, writes a note to stderr and marks the answer `"gap": true` so your own log shows the receipt chain has a hole there. ## Keep the receipt, and check it Every decision comes back with a signed receipt, and the receipt is the record: what was asked, which policy decided, the decision and its reason. Both handlers keep it in two places. The whole receipt is in the answer to your platform, exactly as the gate returned it: "receipt": {"receipt_type": "money_action_authorization", "receipt_id": "rcpt_...", "decision": "allow", "policy_hash": "...", "signature": "...", "public_key_hex": "...", ...} and it is appended to `AGENTGUARD_RECEIPTS_FILE` (default `agentguard-receipts.jsonl` in the working directory), one JSON receipt per line. Store that file, or the `receipt` field, wherever you keep records. Keep the receipt unchanged: a receipt with any field altered no longer verifies. When the gate does not answer there is no receipt, the answer has none, and it is marked `"gap": true`. To check receipts against the published key (https://agentguard.run/.well-known/jwks.json): node verify-receipt.js agentguard-receipts.jsonl node verify-receipt.js receipt.json --jwks jwks.json # offline, with a saved copy of the key list It prints one line per receipt and exits 0 only when every one verifies. A receipt verifies when the key it names is on the published list and its Ed25519 signature matches every other field; the script is about 40 lines of standard library code you can read or port. Without Node, send one to the hosted check: curl -s https://agentguard.run/api/verify -H "content-type: application/json" \ -d "{\"receipt\": $(head -1 agentguard-receipts.jsonl)}" A valid signature says the gate signed this record. It does not say the action was correct. Map your platform's tool names to gate action types in `TOOL_TO_ACTION`. Replace `POLICY` with the operator's policy from the order form. Full contract: https://agentguard.run/vendors ## Limits the agent cannot change **Pin the policy on the key.** AgentGuard stores the operator's policy on the vendor key (`POST /api/vendor/policy`, operator only). A pinned policy decides every request made with the key and any `policy` a request carries is ignored, so an agent cannot send itself a looser one. Each receipt says `policy_source: "pinned"` with the policy's canonical SHA-256 in `policy_hash`, and `request_policy_ignored: true` when a request sent its own. New keys should be issued with a pinned policy and `require_pinned_policy: true`, which refuses any request until a policy is pinned (`403 pinned_policy_required`). Keys without a pinned policy keep working as before, and their receipts say `policy_source: "request"`. **The gate counts the window.** Money allowed under a key is counted by the gate per key and per `window` (`per_day` or `per_hour`). A `window_spent_cents` in the request is not used for a keyed decision; when it differs from the gate's own figure the receipt keeps both (`window_spent_before_cents`, `caller_window_spent_cents`). Concurrent requests cannot together spend past `window_cap_cents`. An action a person approved counts once its result is reported to `POST /api/gate/outcomes` as `succeeded`, `pending` or `unknown`. **Name the payee.** A money action can carry the payee in `recipient_ref`: a Stripe profile handle such as `@acme`, a connected account, a bank or wallet reference. The gate keeps only a keyed hash (`action.recipient_ref_hash` on the receipt), compared without regard to case or spaces. A pinned policy can allowlist payees and cap each one in a rolling 24 hours: "recipients": { "allowlist": ["@acme-supplies", "acct_1ExampleConnected"], "on_unlisted": "escalate", "velocity_per_24h": {"max_count": 3, "max_amount_cents": 200000, "on_exceed": "block"} } The allowlist is hashed when it is pinned and the raw values are not stored. When a recipients rule applies, a payee that is not on the list, or a money action that names no payee, is held for a person (`on_unlisted: "escalate"`) or blocked (`"block"`). Put `"recipients": false` in a rule to turn payee checks off for that action type. `gate_policy_example` with `name: "vendor-payouts-v1"` returns this sample.