Webhook Agent Gate: the one-action pattern and a ten-check handler scan (free sample)

Run python3 hook_mini.py on [handler file]. For every finding, explain the risk in one line and the smallest fix. Do not edit the file.

The rules and script are in the file.

# Webhook Agent Gate: the safe webhook pattern for agents and a ten-check handler scan (free sample)

Version 1.0, 2026-10-31. By PaperChaseWebb. For anyone who lets a Stripe, GitHub, form or store webhook start an agent, a Zap, an n8n flow or a refund. One page and one Python 3 script, standard library only, read-only: it reads handler files and never runs them, sends nothing and reads no secrets. Tested with 3 unit tests and 41 planted faults (each of the ten checks fires) on Linux with Python 3.13, 3.12, 3.11, 3.9 and 3.8, and run on the eight Python and Node webhook servers in Stripe's public accept-a-payment samples.

## The pattern

Providers send the same event more than once, out of order, and keep retrying when your handler is slow or answers with an error. That is normal and documented. It turns into a problem the day the handler starts an agent or moves money, because each copy can run the action again. The safe shape:

1. Verify the signature on the raw body, before parsing. A failed check answers 400 and stops. A missing secret stops the server from starting; it never means "skip the check".
2. Store the event once, under a unique key on the event id (INSERT OR IGNORE or ON CONFLICT DO NOTHING). Answer 200 quickly, including to a duplicate.
3. Do the work later, in a worker. Each action gets a key built from what it acts on (refund:ch_123), not from the event or the run. Two copies of one event, or two events about the same charge, land on one row.
4. Money and a