What an Inspector Is For

Webhooks are how modern APIs say "something happened." Stripe charges a card and POSTs to your endpoint with the result. GitHub merges a PR and POSTs a description of the merge. Twilio receives an SMS and POSTs you the message. The pattern is everywhere, and debugging it has a specific shape: until you've seen one real request from the provider, you don't know exactly what shape it'll be.

That's where the inspector comes in. You generate a temporary URL, paste it into the provider's webhook configuration, trigger a test event, and the inspector shows you exactly what arrived. Headers, body, signatures, encoding, the whole HTTP request as it appeared on the wire.

What You Actually See

When a request hits the inspector URL, you get:

HTTP method and path. Usually POST. Sometimes GET (for verification handshakes) or PUT.

All headers. Including:

• Content-Type, application/json, application/x-www-form-urlencoded, or something stranger.
• User-Agent, identifies the provider ("Stripe/1.0", "GitHub-Hookshot/abc123").
• Signature headers, provider-specific, used for authenticating that the request really came from them.
• Content-Length, Accept, custom X- headers.

Query string. Parsed and shown as key-value pairs.

Body. Both raw bytes and, when parseable, a structured view. JSON is shown with syntax highlighting; form data is parsed; binary is shown as hex.

Source IP. Useful for IP-allowlisting verification.

Timestamp. When the request arrived.

Common Webhook Debugging Tasks

Verifying signature implementation. You wrote signature-verification code and want to test it without rolling back. Hand the provider an inspector URL, trigger an event, copy the raw body and signature header to your tests, and verify your code accepts the real signature. The raw body matters, even a single byte of normalization (re-serializing JSON, changing whitespace) will break HMAC verification.

Understanding payload shape. API docs lie or omit fields. The actual shape is what arrives. Capture a real event and see whether null fields are sent as null or omitted, whether nested objects are stringified, whether enum values match the documented set.

Reproducing a flaky failure. Your handler crashes on certain events and you don't know why. Point the provider at an inspector URL for the duration of a failing scenario, capture the offending request, then replay it against your local server in a debugger.

Verifying webhook routing. You configured a webhook in the provider's dashboard but aren't sure it's set up correctly. The inspector shows whether requests are arriving at all, many "my webhook isn't working" bugs turn out to be misconfigured URLs or disabled webhooks in the provider's UI.

Comparing test vs. live. Many providers send test events with slightly different payloads than real ones. Capture both, diff them, find the differences before they trip your handler.

Webhook Patterns to Know

Signature verification. Every webhook in production must verify signatures. Otherwise anyone who finds your URL can forge events. Standard approach: HMAC-SHA256 over the raw request body with a shared secret, compared with constant-time comparison.

Idempotency. Webhooks can be delivered multiple times, providers retry on transient failures, sometimes aggressively. Treat each webhook as potentially duplicate; use the event ID (Stripe-Event-Id, X-GitHub-Delivery, etc.) to deduplicate.

Order is not guaranteed. Webhook event A may arrive after event B even though A happened first. Don't rely on order; use timestamps in the payload.

Asynchronous, fire-and-forget. Providers retry on 5xx and timeout, but eventually give up. Your handler must respond fast (under 5 seconds usually), do the actual work asynchronously after acknowledging.

Status code semantics. 2xx means "received and accepted." 4xx means "you've sent something I can't handle; don't retry." 5xx means "something's broken on my end; please retry." Be careful with 5xx, repeatedly 500-ing a webhook can get you placed on a retry-quarantine list.

Anti-Patterns

Doing work synchronously in the webhook handler. If you process the webhook in-line and your processing takes 10 seconds, you'll time out, the provider will retry, and you'll be processing the same event multiple times. Push the work to a queue immediately.

Not verifying signatures. Public webhook URLs are findable. Without signature verification, attackers can forge events, fake payments, fake user signups, fake whatever the webhook represents.

Trusting timestamp without validation. Some signed webhooks include a timestamp in the signed payload. If you don't check that timestamp is recent, attackers can replay an old, valid request indefinitely.

Storing webhook URLs in client-side code. Webhooks are server-to-server. If your "webhook URL" is a frontend endpoint, the secret can't be kept secret, and the architecture is wrong.

Workflows

1. New provider integration. Configure provider with inspector URL, trigger sample events, study payloads. Use the captured data to write your handler and tests. Then switch to your real URL.
2. Production incident. Webhook handler crashing in prod. Temporarily mirror a few events to the inspector to capture the exact request that's failing.
3. API client development. Reverse-engineering a webhook from a poorly-documented provider. Inspector reveals the actual format faster than reading docs.
4. CI smoke testing. During pre-deploy, run a synthetic webhook end-to-end and capture in the inspector to verify your handler will accept it.
5. Multi-provider unification. If you accept webhooks from many providers, capture samples from each to design a unified processing pipeline.

Alternatives to Inspector URLs

• ngrok / Cloudflare Tunnel: expose local server publicly; handle requests in your code.
• Provider dashboards: Stripe Events, GitHub deliveries, etc. show captured webhook history with replay buttons.
• Webhook recorders in your own infrastructure: log every incoming webhook to a database for long-term analysis.
• RequestBin / Webhook.site / Pipedream: hosted services with similar functionality.

Privacy Considerations

Captured webhooks may contain sensitive data, order details, customer emails, OAuth tokens, internal IDs. Treat inspector URLs as ephemeral and don't reuse them across unrelated projects. For production webhook debugging on real customer data, use your provider's own dashboard, which keeps captured payloads scoped to your authenticated account.

Captured data in this inspector is held in your browser session only and is not persisted to a third-party server.