Webhook Agent Gate: one action per event, owner-approved refunds and a checker for your handler
by PaperChaseWebb
A small gate between Stripe, GitHub, form or store webhooks and the agent they start. It checks the signature on the raw body, stores each event once, keys every action on what it acts on so a duplicate, a retry or a crash cannot do it twice, and holds refunds for the owner at a terminal the agent cannot use. Includes replay.py to fire duplicates and forged deliveries at your own handler, and a read-only checker for handlers, event maps, ledgers and agent rules.
- Price
- $29
- Difficulty
- Intermediate
- Setup
- 45 min
- Format
- .md file
webhook-agent-gate-one-action-per-event-owner-approved-refunds-checker.md · 205 KB · instant download after checkout
Want this built for you instead? We can build it for you.
What you end up with
Every webhook leads to at most one receipt, one refund and one agent run, money waits for your yes, and you can prove your own handler survives duplicates and forged deliveries before you go live.
What you get
- 20 sections and an appendix in one .md file, with a one-line unpack for all 35 files
- hookgate.py: one endpoint per provider, signature checks for Stripe, GitHub, Standard Webhooks and Lemon Squeezy-style senders, each event stored once
- A ledger keyed on the action (refund:ch_123), an atomic claim, and an unknown state for crashes and timeouts that is looked up, never re-run on its own
- The owner step: refunds wait until the owner types part of the key and a name at a real terminal; piped input is refused
- replay.py: duplicates, a 20-copy burst, forged, tampered, stale and oversized deliveries against your own handler
- hook_check.py: 17 handler checks plus checks for event maps, ledgers and agent rules, tested on Stripe's public sample servers
- Rules and two skills for Grok Bot, Claude Code, Codex and Hermes, six owner stops, eight prompts and a failure table
- The test harness: 97 unit tests, 99 planted faults and 10 interop checks, so you can repeat every result
Who it is for
Anyone who lets a webhook start an agent and wants each event to act once, with a person in charge of the money.
Works with
Solid chips: the agent is named in this listing's own tools list. Dashed chip: A small Python gate in front of the agent or automation your webhooks start. Rules for AGENTS.md and CLAUDE.md, Claude Code settings, Codex and Hermes notes and a Grok Bot standing order. Signatures tested against stripe-python 16.1.0, stripe-node 23.1.0 and standardwebhooks 1.1.0. The agent files were checked by the checker on Linux; they were not loaded inside each agent for this release.
Tools needed
Cost to run: The kit is the only purchase. Everything runs locally with Python; the checker makes no network calls.
Time to result: The checker on a handler you already have in 5 minutes; the gate running with test events in under an hour
How it works
Unpack and test
Save the kit as pack.md in an empty folder, run the unpack line from section 20, then sh test_all.sh.
Expected: 35 files written; 97 tests OK; 99 of 99 planted faults caught.
Check the handler you have
Run python3 hook_check.py code on your webhook route file with --fail-on high.
Expected: A list of findings with fixes, or a clean line.
Watch the flow
Run sh example/run_example.sh and read it next to section 15.
Expected: One receipt and one refund from five deliveries and two refund forms; the forged request refused.
Make it yours
Fill in the event map with the owner, edit gate/events.json, run replay.py suite against the gate with your test secret, then fill in the go-live card.
Expected: Every replay line ok; hook_check events clean.
Sample prompts, free to use
Read AGENTS.md and skills/webhook-gate-builder/SKILL.md. Tell me the stop points in your own words and which kinds in gate/events.json you may propose.
Prompt 1 of 8.
Use skills/webhook-review on [file]. Run hook_check.py code with --fail-on low and explain each high finding in one line with the smallest fix. Do not edit the file.
Prompt 2 of 8.
Read the task in tasks/ for this refund request. Propose the refund with propose.py, then stop and give me the key. Do not run approve.py.
Prompt 5 of 8.
Free preview of the file
# Webhook Agent Gate: one action per event, owner approval for money, and a checker for your own handler Version 1.0, 2026-10-31. By PaperChaseWebb. A small gate that sits between Stripe, GitHub, form or store webhooks and the agent or automation they start. It checks the signature on the raw body, stores each event once, and runs every real-world action (a refund, a receipt, a plan change, an agent task) through a ledger keyed on the action itself, so a duplicate, a retry or a crash cannot do it twice. Refunds wait for the owner at a terminal the agent cannot use. Comes with replay.py, which fires duplicates, bursts and forged deliveries at your own handler, a read-only checker for handlers, event maps, ledgers and agent rules, rules and skills for Grok Bot, Claude Code, Codex and Hermes, and templates. Python 3.8 or later, standard library only. Tested as described in section 12: 97 unit tests and 99 planted faults on Python 3.13, 3.12, 3.11, 3.9 and 3.8, 10 of 10 interop checks against stripe-python 16.1.0, stripe-node 23.1.0 and standardwebhooks 1.1.0, and the checker run on Stripe's public sample servers. All business data is made up. Nothing here was run against a live Stripe or GitHub account; section 12 lists every gap. Providers send the same event more than once. Stripe says so in its webhook docs, GitHub lets you redeliver by hand, and both retry when your handler is slow. A handler that only writes a row shrugs that off. A handler that starts an agent, sends a r
Test record
- Date
- Oct 31, 2026
- What was run
- tests/test_verify.py (22), test_ledger.py (21), test_gate.py (24, real HTTP), test_check.py (27) and test_mini.py (3); tests/mutate.py with 99 planted faults across handlers, event maps, ledgers, agent rules and the gate itself; tests/interop.py, 10 checks with stripe-python 16.1.0, stripe-node 23.1.0, standardwebhooks 1.1.0 and Node 24.22.1; hook_check.py on stripe-samples/accept-a-payment; example/run_example.sh end to end; and the unpack line with test_all.sh. Linux, Python 3.13, 3.12, 3.11, 3.9 and 3.8.
- Result
- 97 passed, 0 failed on all five versions; 99 of 99 planted faults caught; 10 of 10 interop checks; 26 findings on the Stripe samples; the example made one receipt and one refund; the unpack line wrote 35 files and test_all.sh passed there.
- Not run
- Live Stripe or GitHub deliveries, the Stripe CLI and the live Stripe refund adapter. A live Grok Bot, Claude Code, Codex or Hermes session. macOS or Windows. Real business data. Load beyond a few hundred events.
Copied from this item's dated test notes. What was not run stays in.
Worth knowing
- Nothing was run against a live Stripe or GitHub account. Signatures were tested against the official Stripe and Standard Webhooks libraries, and the real Stripe refund adapter is written from the Stripe docs but was not run. Send test-mode events before you switch a live endpoint.
- The agent rules and settings were checked by the checker but not loaded inside a live Grok Bot, Claude Code, Codex or Hermes session for this release. Run prompt 1 once before you rely on it.
- The owner step assumes the agent cannot run approve.py at a terminal or write gate.db. Run the worker and approve.py as a separate user; agent rules alone are not a hard boundary.
- The gate listens on 127.0.0.1 and needs your own HTTPS in front of it for live use. It suits a small business, not thousands of events a second.
- hook_check.py is pattern checks on Python and JavaScript/TypeScript. It does not follow helper functions in other files and does not prove a handler is safe.
- All business data is made up. Tested on Linux only; macOS and Windows were not tested.
- On 2026-10-31 on Linux: 97 unit tests and 99 of 99 planted faults passed on Python 3.13, 3.12, 3.11, 3.9 and 3.8; 10 of 10 interop checks passed; the checker found 26 findings in Stripe's accept-a-payment sample servers; the unpack line wrote 35 files and test_all.sh passed in that folder.
Questions
Which agents does it work with?
Any agent that can read a task file and run a script. The kit has rules for AGENTS.md and CLAUDE.md, Claude Code settings, Codex and Hermes notes and a Grok Bot standing order. Those were checked by the checker, not loaded in each agent for this release.
Can my agent approve a refund?
Not through the gate. The agent can only propose. approve.py needs a real terminal and part of the key typed by hand. Run it as a separate user so the agent cannot reach it at all.
I already have a webhook handler. Do I need the gate?
Not always. Run hook_check.py and replay.py on your handler first. If it passes, copy the ledger idea from section 5 and keep your code.
Does it work with n8n or Zapier?
Put the gate in front and let the worker call your flow as an action, so the flow runs once per action key. The n8n with AI Agents kit covers the approve step inside n8n.
Can you set it up for us?
Yes. Our Install sprint wires it to your Stripe, forms and agents with your own rules. Book a call or write to [email protected].
Details
Version 1.0 · Updated Oct 31, 2026 · Markdown version of this page
License: Use inside your own team or company, including on client work. Do not resell or republish the kit itself. Download terms
Related
Webhook Agent Gate: the one-action pattern and a ten-check handler scan (free sample)
From Webhook Agent Gate: the five-step pattern that makes a webhook act once, six rules for agents that build or touch webhook code, and a read-only script that runs ten checks on a Python or JavaScript handler, from parsing before the signature check and plain string compares to missing duplicate protection and refunds inside the request.
MCP Server Kit: a tested starter server, approval-gated write tools and a checker
A small working MCP server for a made-up plumbing business where every write is a draft plus an apply that waits for the owner, an approval script the agent cannot run for you, and a read-only checker that finds unsafe tools, poisoned descriptions, open schemas, live keys and unpinned packages in any server or agent config, including starters you bought. Tested against the official MCP Python SDK with configs for Grok Bot, Claude Code, Codex and Hermes.
n8n with AI Agents: six tested workflows, an Approve step before every send, and a checker
Six n8n 2 workflows a service business uses every week (lead reply, invoice reminders, review requests, a daily report, an agent request gate and an error alert), each imported and run on a real n8n. Every outside email waits for the owner's Approve click, and Decline or silence sends nothing. A read-only checker finds the same faults in any export, including templates you bought, and a go-live card ties the owner's sign-off to the exact file.
Ask-first rules for AI agents: hard nos, approval cards and a test set
Paste-in rules that make an agent ask before it sends, spends, posts or deletes, define what a real yes is, and stop retries after a no, plus 12 test scenarios to check it.
Backends for Agent-Built Apps: pick a shape, write the contract, keep the data safe
A teaching guide for the server side of apps your coding agent builds. Pick one of five backend shapes with six questions, write a BACKEND.md contract the agent follows, and get migrations, sign-in, access rules, secrets, webhooks, jobs, free tier limits and live monitoring right. Includes backend_check.py, AGENTS.md with six owner stops, two skills, templates and 14 prompts.
Pre-launch security prompts for vibe-coded apps: Supabase RLS, leaked keys and open doors, with two checks you can run yourself
14 prompts that make your coding agent find exposed keys, tables without row level security, open buckets and unverified webhooks in your own app, then fix them one commit at a time. Version 1.1 adds two read-only checks you run yourself: rls_check.sql, which logs in as the public key and as a second user to prove a stranger cannot read your rows, and bundle_scan.py, which finds secret keys in your production build, including a service role key grep cannot see. Both were tested on a made-up app with planted problems.
Wake your bots on real work instead of a timer, and give each one its own read budget
A builder wiring seven Grok Bots into one launch workflow found hourly timers would mean over a thousand mostly empty runs a week. His fix: one scheduled check, every other bot woken by a trigger, a shared ledger for handoffs, a per-bot X read budget, a real dry-run mode and one spending bot behind a hard approval limit.
Show reviewers the effect of an agent's action, not the agent's story about it
A post compares two approval screens for the same agent action: a sentence explaining why, versus the action, record, amount, before and after values, the policy rule that triggered review, whether it can be undone and the source ticket. The second can be judged in seconds from facts.