DEV Community

spoke
spoke

Posted on

I built a local CLI to regression-test Stripe webhooks with real event fixtures

#showdev #node #opensource #testing

I've been working on a small open-source CLI called Spoke Hooks.

The idea came from a simple problem: I wanted a way to preserve real production-shaped webhook events as regression fixtures instead of relying only on generated or happy-path test payloads.

The cases worth preserving are often the ones that involve retries, duplicates, slightly different payload structures, or business-specific data.

So I wanted a workflow that treats real webhook events more like regression fixtures.

The workflow

Install the CLI:

npm install -D @spoke-labs/hooks
Enter fullscreen mode Exit fullscreen mode

Initialize it:

npx spoke-hooks init
Enter fullscreen mode Exit fullscreen mode

Add a Stripe event payload:

npx spoke-hooks add stripe-event.json
Enter fullscreen mode Exit fullscreen mode

Then record the current behavior of your webhook handler:

npx spoke-hooks baseline
Enter fullscreen mode Exit fullscreen mode

After changing your code, replay the same event:

npx spoke-hooks test
Enter fullscreen mode Exit fullscreen mode

If the HTTP status or response body changes, the test fails.

For example:

Expected: { status: 200, body: { received: true } }
Actual:   { status: 500, body: { received: true } }

FAIL
Enter fullscreen mode Exit fullscreen mode

The CLI exits with a non-zero status, so the same test can be used in CI.

What it does right now

The current scope is intentionally small:

  • Stripe
  • Node.js
  • Express
  • local HTTP replay
  • JSON fixtures stored in the repo
  • HTTP status comparison
  • response body comparison
  • timeout / request failure handling
  • CI-friendly exit codes

There is no hosted backend, account, dashboard, or cloud storage.

The fixtures stay inside your project.

Why baseline instead of only asserting 200?

The part I’m experimenting with is treating the current behavior of a real event as a baseline.

So instead of writing every expected response manually, the flow is:

real event
   ↓
current handler behavior
   ↓
baseline
   ↓
code change
   ↓
replay same event
   ↓
compare
Enter fullscreen mode Exit fullscreen mode

It’s basically a lightweight behavioral regression test for webhook handlers.

What I’m trying to learn

The CLI itself is working and is already published on npm, but I’m more interested in whether this workflow actually fits how people maintain webhook integrations.

If you work with Stripe webhooks, I’d especially like feedback on:

  • Do you keep real webhook payloads as fixtures today?
  • Would a baseline + replay workflow be useful in your CI?
  • What would make this annoying to use in a real project?
  • Is comparing status + response body enough to start with?
  • Would production-event capture and sanitization be the valuable part, or not really?

GitHub:

Spoke Hooks on GitHub

npm:

npm install -D @spoke-labs/hooks
Enter fullscreen mode Exit fullscreen mode

I’m keeping the scope small for now and trying to validate the workflow before building anything bigger.

Top comments (0)