DEV Community: Webappers

Testing Stripe webhooks locally without ngrok

Webappers — Mon, 31 Aug 2026 09:58:16 +0000

The standard advice for testing webhooks locally is "use ngrok". It works, but it's the wrong first answer for Stripe specifically, because Stripe ships a free tool that does the job better and doesn't expose your laptop to the internet.

Here's the whole thing, plus the two situations where you do need something else.

The Stripe CLI does this for free

**
Install it, log in, and forward events straight to your local server:

stripe login
stripe listen --forward-to localhost:3000/webhooks/stripe

That prints a signing secret on startup:

> Ready! Your webhook signing secret is whsec_1234abcd... (^C to quit)

This secret is different from the one in your Dashboard. It's specific to this listen session. Put it in your local env, not your production one — using the Dashboard's secret while running stripe listen is one of the most common causes of signature verification failures:

STRIPE_WEBHOOK_SECRET=whsec_1234abcd...

Then in a second terminal, fire an event:

stripe trigger payment_intent.succeeded

No tunnel, no public URL, no firewall exposure. It also survives restarts of your dev server, which ngrok URLs on the free tier famously do not.

Filter to the events you care about

stripe listen forwards everything by default, which gets noisy fast:

stripe listen \
  --events payment_intent.succeeded,customer.subscription.updated \
  --forward-to localhost:3000/webhooks/stripe

The raw body trap, since you'll hit it anyway

Signature verification hashes the exact bytes Stripe sent. If a body parser turned them into an object first, verification cannot succeed. In Express, order matters:

// This route must be registered BEFORE express.json()
app.post('/webhooks/stripe',
  express.raw({ type: 'application/json' }),
  (req, res) => {
    const event = stripe.webhooks.constructEvent(
      req.body,                                  // Buffer, untouched
      req.headers['stripe-signature'],
      process.env.STRIPE_WEBHOOK_SECRET
    );
    res.json({ received: true });
  }
);

app.use(express.json());                          // everything else after

n the Next.js App Router, use await req.text() — never await req.json().

Where the CLI runs out

Two cases, and they're both about the same thing: stripe trigger sends a synthetic event. It's generated by Stripe to be well-formed, not drawn from your account.

Your real events don't look like the synthetic ones Synthetic events have empty metadata, no connected-account fields, no expansions, and none of the quirks your actual integration produces. If your handler reads metadata.orderId that you set at checkout, stripe trigger will never populate it, and the handler will look broken locally while working in production — or, worse, the reverse.

To see what your account actually sends, you need to capture a real event. Add a second webhook endpoint in the Dashboard pointing at a request-capturing URL. Stripe delivers to every configured endpoint, so this sits alongside your real one and breaks nothing.

You need the same event more than once Some events are genuinely hard to produce on demand — a subscription renewal, a dispute, a failed payment retry. stripe trigger can fake the shape but not your specific instance of it.

The Dashboard has a Resend button on each event under Developers → Events, which re-delivers that exact event to your endpoints. That's free and it's often all you need. Its limits: it fires at your registered endpoint, so it can't target localhost unless stripe listen is running, and you can't modify the payload before resending — which you often want to do while narrowing down which field breaks your handler.

For that loop — capture once, edit, fire repeatedly at your own endpoint — you need a dedicated tool. Hookdeck has a free tier and does it well. webhook.site captures free with no signup but is oriented at inspection rather than replay. I build Eventfy, which is a paid product built around exactly that edit-and-refire loop — mentioned for completeness, and the free options above genuinely cover most of what's in this post.

The short version

Local development: stripe listen --forward-to. Free, no tunnel, use the secret it prints.
Seeing what your account really sends: a second endpoint pointing at a capture URL.
Replaying one event repeatedly: Dashboard Resend first; a replay tool if you need to modify the payload between attempts.
ngrok is a good tool that you mostly don't need here.

Your AI wrote that webhook handler from the docs. The docs are abridged.

Webappers — Mon, 31 Aug 2026 09:52:26 +0000

There's a specific bug I've hit enough times to recognise on sight now, and I haven't seen it written up. It comes from a habit that is otherwise a good one: asking an AI assistant to write your webhook handler.

The handler it produces looks right. It passes review. It matches the provider's documentation exactly. And then the first real event hits it in production and it throws on a field that isn't there.

Why this happens specifically with webhooks
An AI assistant writes your handler from what it learned: the provider's documentation, blog posts, and Stack Overflow answers. For most code that's fine — the docs for a REST client describe the REST client accurately.

Webhook documentation is different, because documentation payloads are abridged on purpose. A real Stripe payment_intent.succeeded event is several hundred lines. Nobody would put that in a getting-started guide, so the docs show a trimmed version with the interesting fields and an ellipsis. That trimmed version is entirely honest as documentation and entirely misleading as a schema.

So your assistant writes a handler for the illustration, not for the payload. And it has never seen your actual account's events, because nobody publishes those — they're full of real customer data.

The result is a handler that is confidently wrong in a small number of predictable ways.

The four shapes this takes

Nesting that the example flattened Clerk's user.created is the one that gets everybody. There is no email on the user object. There's an array of email addresses, plus a pointer to which one is primary:

// What an assistant tends to write
const email = evt.data.email;                    // undefined

// What Clerk actually sends
const { email_addresses, primary_email_address_id } = evt.data;
const email = email_addresses.find(
  e => e.id === primary_email_address_id
)?.email_address;

The first version doesn't throw. It writes undefined into your database and you find out days later.

Absent versus null Docs examples usually show every field populated, because a field with a value is more instructive than one without. So the assistant writes:

if (event.data.object.metadata.orderId) { ... }

metadata is {} on most real events, which is fine. But on some providers optional objects are omitted entirely rather than sent empty — and then metadata is undefined and this line throws Cannot read properties of undefined. Optional chaining costs nothing and is the whole fix:

if (event.data.object.metadata?.orderId) { ... }

Expandable fields that arrive as strings This one is Stripe-specific and genuinely nasty. Several fields are either an ID string or a full object depending on how the event was created and what was expanded. The docs example shows the expanded object. Reality often sends the string:

// Works in the docs example, throws on half your real events
const customerEmail = event.data.object.customer.email;

// Actually safe

const customer = event.data.object.customer;
const customerId = typeof customer === 'string' ? customer : customer?.id;

The envelope, not the row Supabase database webhooks don't send you the row. They send an envelope describing what happened to it:

{
  "type": "INSERT",
  "table": "orders",
  "schema": "public",
  "record": { "id": 1, "status": "paid" },
  "old_record": null
}

Assistants routinely write const { id, status } = payload and get nothing, because the row is under record. On UPDATE you also need old_record to know what changed, and on DELETE the row is in old_record and record is null.

Why testing doesn't catch it
Because the test fixture has the same ancestry as the bug. You ask for tests, and the assistant writes a fixture — from the same documentation example that produced the handler. The handler passes against a payload shaped exactly like the one it was written for. Both are wrong in the same direction, so they agree.

Provider test tools help less than you'd hope, too. stripe trigger payment_intent.succeeded sends a synthetic event, and synthetic events are also idealised. They're generated, not drawn from your account. The mismatch you care about is between the docs and your real traffic.

The fix is boring and it works
Stop writing handlers against documentation. Write them against one real payload.

Capture one real event. Add a second webhook endpoint in your provider's dashboard pointing at any URL that records raw requests. Providers fan out to every configured endpoint, so this runs alongside your real handler and changes nothing.
Trigger it for real. Not the test button — make an actual test-mode purchase, sign up an actual user. You want your account's real output.
Diff it against what your handler assumes. This takes about two minutes and is where you find all four bugs above at once.
Save that payload as your test fixture. Now your tests are anchored to reality rather than to the same illustration that produced the bug.
Replay it while you fix. Being able to fire the identical request at your handler repeatedly is the difference between a ten-minute fix and an afternoon of making test purchases.
Step 5 is the one people skip, and it's the one that hurts. Without replay, each iteration means generating a fresh real event, which for something like a subscription renewal can be genuinely difficult to produce on demand.

Tools for the capture step
webhook.site is free, needs no signup, and is perfect for steps 1–3. Open it, copy the URL, done. For a one-off diff it's all you need and I'd start there.

For step 5 you want something that stores events and re-fires them at your own endpoint. Hookdeck does this and has a free tier. I built Eventfy for the same loop, aimed specifically at people shipping AI-written code — it's a paid product with a trial, so weigh it accordingly.

The tool matters much less than the habit, though. One real payload, captured before you write the handler, prevents every bug in this post.

If you've hit a fifth shape of this I haven't listed, I'd genuinely like to hear it — I suspect there are more.

The hardest part of vibe coding isn't building the app

Webappers — Wed, 19 Aug 2026 10:36:49 +0000

I've been thinking about this a lot lately.

With Claude, Codex, Cursor, etc., I can get an app from an idea to something working ridiculously quickly.

And honestly, that's great.

But then comes the part that isn't as fun.

You put it in front of actual users.

Someone does something you didn't think of.

An API returns something weird.

A background job fails.

A user creates an account and the account doesn't get added.

An AI-generated function technically works, but under one specific condition it does the completely wrong thing.

And suddenly you're spending more time figuring out what actually happened than fixing the problem.

That's the bit I think we're going to underestimate with vibe coding.

We're getting much better at creating software.

We're not necessarily getting better at knowing when the software is quietly going wrong.

That's why I've been building Shipsure.

The idea is to give AI-built apps another layer of visibility around the stuff that tends to go wrong once they're actually being used.

Not another AI coding agent.

Not another "paste your error into AI" tool.

More like:

Your app broke. Here's exactly what happened.

I'm still figuring out what the product should become, so I'm genuinely curious about this:

What's the most annoying bug you've had in an AI-built app that took way longer to find than it should have?

Not the biggest bug.
The stupid one.

The one where you eventually found it and thought "there is absolutely no reason this took me 3 hours."

Those are the problems I'm interested in.

I kept wondering why my AI-built apps kept breaking after they worked

Webappers — Wed, 19 Aug 2026 10:24:44 +0000

AI coding tools have made building an app ridiculously fast.

You can describe an idea to Claude, Cursor or Codex and have a working application in a matter of days or minutes depending on the project.

The part I'm finding more interesting now is what happens after you've shipped it.

Because most modern apps aren't really one application anymore.

You've got Stripe talking to your backend.

Shopify sending webhooks.

Supabase handling your database.

Resend sending emails.

Slack receiving notifications.

Some random API you needed for one feature.

And then you've got AI agents sitting somewhere in the middle doing things too.

Everything works great...
Right?

The webhook problem

One of the easiest examples is a webhook.

Say someone pays through Stripe.

Stripe sends your application an event.

Your backend processes it.

You update the database.

Then maybe you send a Slack notification.

Pretty simple.

Until your endpoint returns a 500.

Or the server times out.

Or your code throws an error because the payload wasn't what you expected.

Or the third-party API is temporarily down.

Now you've got an event that didn't get processed.

And unless you've built the monitoring yourself, you might not even know it happened.

I've ended up writing the same kind of stuff over and over:

receive webhook
↓
process it
↓
something fails
↓
log error
↓
try to figure out what happened
↓
manually reproduce it
↓
fix it
↓
try again

And that's before you even start thinking about retries.

This gets worse with AI-built applications

I think this is one of the less-discussed problems with vibe coding.

AI has made the building part dramatically easier.

But it also makes it incredibly easy to end up with an application that has 15 different integrations held together by code you generated three weeks ago.

You might know roughly what the system does.

But when something fails at 2am, you don't necessarily know:

Which event failed
What payload was received
Which endpoint processed it
What response came back
How long the request took
Whether it was retried
Whether the failure came from your app or the third-party service

That's the part that becomes painful.

So I built Eventfy

Eventfy is basically a place to see what's happening with your webhooks and integrations.

You can inspect events, see their delivery history, retry failed requests and replay events when you need to.

Instead of having:

Stripe → ??? → your application

you actually get somewhere to see what happened in between.

The goal isn't to add another giant infrastructure platform to your stack.

It's to make those annoying integration problems much easier to understand.

I think this becomes more important as AI coding gets better

There's an interesting irony here.

The better AI gets at writing software, the more software people are going to ship.

And the more software people ship, the more integrations they're going to have.

Which means the bottleneck might move from:

"Can I build this?"

to:

"Can I actually keep this thing running?"

AI can write the webhook handler.

It can write the API integration.

It can write the retry logic.

But when something inevitably goes wrong, you still need to know what happened.

That's the problem I'm interested in solving with Eventfy.

Building the app is getting easier. Keeping everything connected is still a pain.