DEV Community: Adrian Orenes

Debug a webhook locally: capture once, fix, and replay

Adrian Orenes — Sun, 18 Oct 2026 08:51:55 +0000

A webhook fails, you fix the handler, and now you need the same request again. Creating another checkout or pushing another commit gives you a new event. That makes it harder to tell whether your fix handles the original failure.

This walkthrough uses Hooklistener, which I work on, to forward requests to localhost and replay a captured delivery. Use a development or staging environment with test data.

1. Forward requests to your local handler

Start your application on port 3000, then install the CLI and sign in:

npm install -g hooklistener
hooklistener login
hooklistener tunnel --port 3000

The tunnel prints a public HTTPS URL. If your handler is at /webhooks/stripe, append that path to the URL when configuring your provider:

https://YOUR-TUNNEL.hook.events/webhooks/stripe
    → http://localhost:3000/webhooks/stripe

Use the actual URL printed by the CLI. Send a test event from your provider, then check both your application logs and the captured request in Hooklistener. Requests passing through the tunnel are available for inspection and replay.

If the provider already sends to a Hooklistener endpoint, you can forward that endpoint instead:

hooklistener listen --endpoint YOUR_ENDPOINT_ID --port 3000 --path-prefix /api/webhooks

Choose the path prefix that matches your local routes. The listen reference explains the command options.

2. Inspect the delivery before changing code

Open the captured request and check its method, path, headers, and raw body. Compare those with what your handler expects. A wrong route and a signature failure need different fixes, even if both look like a failed webhook in the provider dashboard.

Keep the original event ID nearby. It helps you correlate the captured request, your logs, and any downstream job.

3. Replay the captured request

After fixing the handler:

Open the original request in Hooklistener.
Choose Replay.
Set the destination to your tunnel URL, including the handler path.
Send the request and inspect the recorded response.
Repeat against the same captured request after each change.

This sends a stored delivery to your chosen destination. It does not ask the provider to create a new event. Capture must already be in the delivery path: Hooklistener cannot reconstruct a request it never received.

A successful HTTP response is only part of the check. Confirm that the expected development-side effect happened, such as a test order changing status or a job being queued.

Two reasons a replay can still fail

Signature verification. Some providers include a timestamp in the signed data. An older captured request can fail the receiver’s freshness check even when the payload is unchanged. Editing the body can also invalidate its signature. Keep signature verification enabled. Hooklistener supports re-signing Stripe, GitHub, and Slack replays through its MCP replay tool using a stored signing secret; stored secrets require a paid plan. Use the appropriate test-environment secret.

Deduplication. A replay retains the event ID. If your handler has already processed that ID, skipping it may be correct behavior. To test processing again, use isolated development state. Also test the duplicate path deliberately: processing one event twice should not create two orders or send two emails.

Turn the failure into a regression case

Once the fix works, save the captured request as a replay case. Rerun it against development or staging after future changes, checking both the response and the side effect. Keep a duplicate-delivery case alongside it.

The useful loop is small: capture a real test delivery, inspect it, change the handler, and replay the same input. You can debug the failure without repeatedly recreating the provider-side event.

References: CLI tunnel setup · Replay guide.

I finally stopped using ngrok for Stripe Webhooks.

Adrian Orenes — Fri, 27 Feb 2026 16:01:49 +0000

Debugging Stripe Webhooks without the Alt-Tab Fatigue

I’ve spent an embarrassing amount of time in my career doing the "Stripe Dance."

You know the one: Trigger a test event in the Stripe dashboard, alt-tab to the terminal to see if ngrok caught it, alt-tab to the editor to tweak a console.log, then realize the ngrok tunnel timed out because you were over the free limit.

The Stripe CLI helps a lot, but you’re still squinting at a terminal buffer trying to find that one customer_id nested five levels deep in a JSON blob.

I recently started using the Hooklistener MCP server with Claude Code, and it’s the first time webhook integration hasn't felt like a chore. Here’s how the workflow actually feels.

The Setup (The boring part)

If you're using Claude Code, Cursor, or Windsurf, you just drop this into your MCP config. No binaries to install, no daemon to manage.

{
  "mcpServers": {
    "hooklistener": {
      "type": "streamable-http",
      "url": "https://app.hooklistener.com/api/mcp",
      "headers": { "Authorization": "Bearer hklst_your_key" }
    }
  }
}

The Workflow: Let the AI do the "Watching"

The big shift here isn't just "seeing" the webhook; it's having the AI watch for it while you keep coding.

1. Creating a throwaway endpoint

Instead of a permanent staging URL, I just ask Claude: "Give me a new debug endpoint for Stripe Checkout." It hits the create_endpoint tool and gives me a URL. I paste that into Stripe once. Unlike ngrok, this URL stays alive.

2. The "Wait for it" moment

This is where it clicked for me. I was working on an Elixir handler for checkout.session.completed. I told Claude:

"Wait for a request on the Stripe endpoint. I'm going to trigger a test event now."

I went to Stripe, hit "Send test webhook," and instead of me hunting for the log, the payload just appeared in my chat.

3. Writing the code with context

Because the payload was right there in the conversation, I didn't have to copy-paste JSON into the prompt. I just said: "Based on that payload, write the handler. Make sure it pulls the 'plan_id' from the metadata."

The AI isn't guessing based on outdated docs; it's looking at the exact byte-for-byte request Stripe just sent.

Where this actually saves you

I found two specific scenarios where this beats the old terminal-tailing method:

Comparing Events: I captured a successful payment and a failed one. I asked Claude: "Compare these two payloads. Why did the metadata missing in the second one?" It did a diff and realized I’d forgotten to pass the client_reference_id in my frontend code. Doing that manually with two terminal windows is a headache.
Simulating the "What if": Hooklistener lets you set up mock responses. I set the endpoint to return a 500 to see how my app handled Stripe's retry logic. I could see the retry headers (Stripe-Should-Retry) appearing in the list_requests tool without leaving the editor.

Is it perfect?

No. You still have to go to the Stripe dashboard to paste the URL (Stripe doesn't have a "Create Webhook" API that works easily for local dev). And sometimes the AI gets over-excited and tries to explain the whole JSON structure when I just want one field.

But compared to the "Alt-Tab Dance"? I'm never going back. If you’re already using an AI assistant, adding the Hooklistener MCP is a 2-minute upgrade that pays for itself the next time you have to debug a nested JSON object.

Check it out at hooklistener.com.