HookChaos: Webhook Stress Tester CLI/Open-Sourced Project
Source: Dev.to
An order got fulfilled twice. It took two days to figure out our handler wasn’t idempotent and the provider was retrying on timeout. Fine, lesson learned.
Then it happened again. Different bug, same category—a webhook edge case we never tested for because our “testing” was basically: send a ping, get a 200, ship it.
That’s when I realized we had no real way to test the bad stuff: duplicate events, out‑of‑order delivery, delayed events hitting stale state, signature validation breaking over a trailing newline. We just hoped production wouldn’t surface them.
Production always surfaces them.
So I built HookChaos—a local‑first CLI that throws these scenarios at your endpoint before production does.
http://localhost:3000/webhooks
HookChaos
HookChaos is the package manager for webhook failure scenarios. It is a local‑first CLI for reproducible webhook failure simulation, built for the bugs that only show up when webhook consumers see:
- Duplicates
- Out‑of‑order deliveries
- Retries that land after state has changed
- Signature or timestamp validation failures
- Selective drops in a sequence
HookChaos turns those failure modes into reusable packs you can run on demand, save locally, publish to a Git‑backed registry, and replay from history.
Why This Exists
Most webhook tooling helps you receive traffic, but that isn’t enough when the real bug is in what happens after the first happy‑path request:
- The same event is delivered twice.
- A later event arrives first.
- A retry lands after your state already changed.
- Signature or timestamp validation rejects an otherwise valid payload.
- One delivery disappears while the rest of the sequence continues.
Install
# Install HookChaos into ~/.local/bin
cd /path/to/hookchaos
make install
export PATH="$HOME/.local/bin:$PATH"What’s the worst webhook bug you’ve dealt with? (That’s literally how the scenario list is going to grow.)