Skip to main content

Debugging Webhooks

Most bugs in a webhook integration aren't bugs in your code. They're missing context: an event you can't see, a payload you can't replay, a signature error masking the real problem. This guide walks through how to actually debug webhooks — first with Svix Play for inspection and local development, then with Svix Ingest when you need a real receiver you can debug in production.

Why webhooks are hard to debug​

Webhooks resist the usual debugging tools for a few specific reasons:

  • They're asynchronous and one-way. The sender doesn't wait for you. By the time you notice something is wrong, the event is gone and the sender has moved on.
  • Payloads are ephemeral. Without a place that captures requests, there's no way to re-examine what actually arrived. "What did Stripe send us at 03:14?" turns into a forensic exercise.
  • Your laptop isn't reachable. Providers can't POST to localhost. Any local debugging requires a public URL that forwards to your machine.
  • Signature errors hide real bugs. Every provider signs differently, and a single typo in your verification code turns every legitimate request into a 401. The actual handler bug never gets exercised.
  • Retries and timing. A flaky handler doesn't fail loudly — it fails, gets retried minutes or hours later, and the resulting log smear is hard to map back to a single root cause.
  • You don't own the sender. When the bug is upstream (a missing header, a payload shape change), you need a record of what actually arrived to file a credible ticket.

Each of these has a different right tool. The rest of the guide walks through them.

Inspecting and replaying webhooks with Svix Play​

Svix Play is a free, no-signup webhook inspector. You get a persistent URL like https://play.svix.com/in/e_94XdF.../ and any HTTP request sent to it shows up in the browser with the full headers, body, and signature visible. It's the fastest answer to two of the most common debugging questions:

  • Is the provider actually sending anything? Configure your provider to point at the Play URL and watch the dashboard. Nothing arriving means the problem is upstream, not in your handler.
  • What does the raw payload actually look like? SDKs and documentation lie. Play shows you the bytes that arrived, byte-for-byte, including the headers the SDK normally hides.

Because the URL is persistent and shareable, it doubles as a way to send a colleague or a support engineer a live repro: "here's the URL the failing webhook went to, look at request #4." There's also an API for asserting on captured payloads from a test suite if you want to bake Play into automated checks.

Forwarding Svix Play to your local server​

Inspection is enough to find a lot of problems, but eventually you want the request to actually hit your code so you can step through your handler, iterate on signature verification, or watch your database get written to. The Svix CLI turns a Play URL into a localhost tunnel:

svix listen http://localhost:8080

The CLI prints a play.svix.com URL and relays every request it receives to localhost:8080. Point your provider at that URL and your local server starts seeing live webhook traffic, while Play continues to capture every request for inspection and replay.

Two practical reasons to prefer this over a generic tunneling tool: the URL is stable across restarts (no reconfiguring your provider every time you restart svix listen), and the free tier doesn't put limits on the URL or the dashboard.

Debugging production webhooks with Svix Ingest​

Play is the right tool for development and ad-hoc inspection, but it isn't where you point your production webhook traffic. When real revenue starts flowing through a webhook endpoint, the debugging problem changes: you need every event captured durably, signatures verified before anything reaches your code, and the ability to replay a specific event from last Tuesday after you fix the bug it triggered.

Svix Ingest sits in front of your real webhook endpoint as a managed gateway. From a debugging perspective it gives you five things that compound:

  • Verified-only events. Ingest has built-in signature verification for Stripe, GitHub, Shopify, Slack, HubSpot, Zoom, Resend, and most other major providers. Your code never sees an unverified request, so "invalid signature" errors stop drowning out real handler bugs.
  • Durable storage and one-click replay. Every event is stored. When you fix a bug, you can replay the exact event that triggered it instead of waiting for the next occurrence (or convincing the provider to resend). "It only fails at 3am" becomes a thing you can reproduce at 11am.
  • Polling endpoints. Instead of exposing an inbound URL, your service can pull events from Ingest over outbound HTTPS. Useful when your handler is on a restricted network, running on a developer's laptop, or you just don't want a public ingress to manage.
  • Transformations and filtering. Reshape or drop payloads in JavaScript before they reach your code. Less noise to debug, and the input to your handler becomes something you control rather than whatever the upstream provider decided to send this quarter.
  • A searchable dashboard. Headers, body, verification result, every delivery attempt and response — all queryable. When something goes wrong, you're reading the actual request that arrived, not piecing it together from your own logs.

The net effect is that debugging stops being forensics. Instead of "the only evidence is in our logs and we didn't log enough," you have the original event, the verification result, every delivery attempt, and a replay button.

Building webhooks?
Svix is the enterprise ready webhook receiver. With Svix, you can have a secure, reliable, and scalable webhook receiver in minutes. Give it a try!

If you send webhooks with Svix, your customers already get this​

The other side of debugging webhooks is being on the receiving end of yours. If you're sending webhooks with Svix, your customers get a debugging experience that you didn't have to build: the App Portal.

The App Portal is an embeddable, white-labeled dashboard that drops into your existing UI. Your customers don't need a Svix account — they don't need to know Svix exists — and from a single magic link they can:

  • See full delivery history for every endpoint they've configured.
  • Inspect each attempt: request headers, payload, response status, signature, timing.
  • One-click replay any past message after they fix a bug on their end.
  • Manage their own endpoints and rotate signing secrets without filing a support ticket.

This matters because the worst debugging experience for your customers becomes your problem: it's the support tickets, the "can you resend the webhook from Tuesday?" emails, the integrations that quietly stop working. The best version of that experience is one where customers can answer those questions themselves, in a UI that looks like yours.

Building webhooks?
Svix is the enterprise ready webhooks sending service. With Svix, you can build a secure, reliable, and scalable webhook platform in minutes. Looking to send webhooks? Give it a try!

Summary​

Debugging webhooks is mostly about getting visibility into events that are otherwise invisible:

  • Use Svix Play to inspect what's arriving and to forward webhooks to your local server during development.
  • Use Svix Ingest when you need verification, durable storage, and replay for a production receiver.
  • And if you're the one sending webhooks, Svix Dispatch gives your customers the same kind of debugging experience out of the box, via the embedded App Portal.