Debug a Failing Webhook

Scenario

A Stripe or Twilio webhook is returning errors. Your endpoint receives a POST but responds with a non-2xx status. You need to see exactly what the provider is sending and what your server returns.

Prerequisites

  • RoxyProxy installed (npx @rvanbaalen/roxyproxy)
  • Your webhook endpoint running locally
  • A way to trigger the webhook (Stripe CLI, Twilio console, etc.)

Manual Steps

Start tailing requests filtered to the webhook provider:

roxyproxy requests --tail --host stripe.com

Trigger the webhook from the provider dashboard or CLI. You will see the request appear in the TUI in real time.

Once you spot the failing request, query for it directly:

roxyproxy requests --host stripe.com --failed --format agent

The --failed flag filters to non-2xx responses. The --format agent flag outputs the full request and response bodies as structured text, making it easy to read the exact error your server returned.

Inspect the response body to find the error. Common causes:

  • Schema mismatch — the provider updated their payload format
  • Missing signature verification header
  • Incorrect content-type handling

With Your AI Agent

If you have the AI Agent Plugin installed, you can skip the manual inspection entirely:

You: "The Stripe webhook at /api/webhooks/stripe is failing. Debug it."

Your agent queries: roxyproxy requests --host stripe.com --failed --format agent
The agent finds the 422 response, reads the error body, identifies the
schema mismatch, and fixes the code.

Your agent reads the captured traffic, correlates the request payload with your handler code, and applies the fix — all in one step.

← All Recipes Trace 422 Errors →