ReqPour — Catch, Inspect & Relay Webhooks

Introduction: What webhook inspection is and why it matters

Webhook inspection is the process of capturing, viewing, and analyzing the full HTTP POST request sent to a webhook endpoint, including headers, payload, and delivery metadata. When a webhook fails, the problem is often hidden in the request itself: malformed JSON, missing headers, bad signature verification, or retry behavior that changes what your system receives.

That makes webhook inspection different from webhook testing and debugging. Inspection is the visibility layer: it shows you the raw traffic. Testing checks whether a webhook behaves as expected before or after deployment. Debugging goes deeper to find the root cause of a failure. If you want a broader primer on the concept itself, see what is a webhook, and for validation workflows, the webhook testing guide is a useful companion.

Common cases include payment webhooks from Stripe or PayPal, CI/CD notifications from GitHub or GitLab, and API integration callbacks from tools like Slack, Shopify, or Twilio. This guide shows how to inspect webhooks locally and in hosted tools, what to look for in the payload and headers, and how to use that data to fix delivery issues, signature mismatches, and retry problems. If you need a deeper troubleshooting path, the webhook debugger helps connect inspection data to root cause analysis.

What is webhook inspection?

Webhook inspection means observing the exact HTTP request an external service sends to your endpoint: the method, URL, query parameters, headers, JSON payload, and timestamp. You can do this in a webhook debugger, a payload viewer, a local tunnel, a hosted endpoint, or production monitoring.

Unlike logging, inspection gives interactive visibility into the raw request you actually received, not just what your app recorded. That makes it easier to spot malformed payloads, missing fields, bad Content-Type values, and signature verification failures. Use it in development, staging, and production to diagnose delivery failures and confirm webhook behavior end to end.

How do you inspect a webhook request?

Start by capturing the request in a tool that can show the full HTTP exchange. A webhook inspection tool should display the request method, URL, headers, body, query string, response status, and timing. If the tool supports raw and parsed views, compare both so you can confirm that the sender’s payload matches what your application code sees.

Then check the request in this order:

Confirm the endpoint received an HTTP POST at the expected time.
Review the HTTP headers, especially Content-Type, User-Agent, X-Signature, X-Hub-Signature-256, request IDs, and any provider-specific event headers.
Validate the JSON payload against the provider’s schema and your own application rules.
Verify the signature using the raw body, the shared secret, and the provider’s HMAC algorithm.
Compare the delivery metadata with your application logs using a correlation ID or event ID.

This workflow is useful whether you are inspecting a live production event, a staging environment test, or a request sent to localhost through a tunnel.

How webhook inspection works

A third-party service sends an HTTP POST to a unique webhook endpoint, and the inspection tool captures the full request before you review it. You then inspect the payload, headers, query string, and delivery metadata in a raw or parsed view, which makes it easier to spot schema changes, missing fields, or auth problems. This is the core workflow behind endpoint testing and most webhook testing guide setups.

Unique endpoints matter because they keep traffic separated by app, environment, or test case. You can point Stripe to one endpoint for staging, GitHub to another for localhost via tunnels, and a separate URL for a single failing test.

Advanced tools add request replay, request forwarding, routing rules, custom responses, and request transformation. That lets you resend the same event, normalize payloads before forwarding, or simulate edge cases without changing the sender.

What should you look for in webhook headers?

Check the HTTP headers first because they often tell you whether the request is authentic, complete, and correctly routed. Content-Type should match the body format, usually application/json for a JSON payload. User-Agent should identify the provider or integration. Event headers such as X-GitHub-Event, X-Signature, or X-Hub-Signature-256 should match the expected webhook delivery.

Also look for request IDs or event IDs that help you trace a single delivery, retry headers that indicate a resend, and timestamp headers when signature verification depends on freshness. If the headers do not match the provider’s documentation, the issue may be on the sender side, in a proxy, or in your own webhook endpoint configuration.

How do you validate a webhook payload?

Validate the JSON payload against the provider’s documentation and your application schema. Check for required fields, data types, nested object structure, array shape, null values, and version changes. A payload viewer helps compare the raw body with the parsed object so you can see whether the sender omitted a field or your code dropped it during parsing.

Schema validation is especially important for payment webhooks and event-driven workflows, where a small payload change can break downstream jobs. If the provider includes an event type, object ID, or status field, confirm that those values match the event you expected to receive.

How do you verify a webhook signature?

To verify a webhook signature, recompute the signature from the exact raw request body using the shared secret and the provider’s documented HMAC algorithm, then compare it with the signature header. If the provider uses a timestamped scheme, include the timestamp exactly as documented and reject stale requests.

Common failure points include parsing the body before verification, using the wrong secret for the environment, reading the wrong header name, verifying against a transformed payload, and clock skew when the provider signs timestamped requests.

For security-sensitive integrations, keep signature verification enabled in both development and production, and review webhook security before relaxing any checks.

How do you inspect webhooks locally?

To inspect webhooks locally, expose localhost through a tunnel so a third-party service can reach your machine. Tools like ngrok create tunnels that forward external traffic to your local server, which is useful when you are building or debugging an API integration.

A practical local workflow looks like this:

Run your app on localhost.
Start a tunnel and copy the public URL.
Configure the provider to send webhooks to that URL.
Capture the request in a local webhook debugger or payload viewer.
Compare the incoming request with your app logs and response status.

Local inspection is useful for reproducing issues before they reach production, but it should not replace staging or production validation.

What tools can be used for webhook inspection?

Common tools include Webhook.site, Beeceptor, Hookdeck, and ngrok. Each supports a slightly different workflow:

Webhook.site is useful for quickly capturing a request and viewing headers and body.
Beeceptor is helpful when you want mock endpoints, routing rules, and custom responses.
Hookdeck is designed for webhook delivery, replay, forwarding, filtering, and observability.
ngrok is useful when you need tunnels to inspect requests sent to localhost.

A good webhook debugger or payload viewer should also support request replay, request forwarding, search, filtering, and access controls. Those features make it easier to compare a failed delivery with a successful one.

Why is webhook inspection important for debugging?

Webhook inspection is important because it shows the exact request that reached your system, not the request you expected to receive. That distinction helps you separate sender problems from receiver problems.

Use inspection to answer three questions:

Was the webhook delivery sent at all?
Did it reach the endpoint?
Did the application accept or reject it?

If the event never appears, the provider may not have fired it, or the webhook endpoint may be misconfigured. If it appears in the inspector but not in your app, check routing rules, firewall rules, proxy settings, and authentication. If your app receives it but returns an error, inspect validation, parsing, and signature verification.

What causes webhook delivery failures?

Common causes include timeouts, non-2xx responses, invalid endpoints, rate limiting, malformed payloads, signature mismatches, and retry logic that keeps resending a failing event. Delivery can also fail when the receiver is down, the body is changed in transit, DNS is misconfigured, or a proxy blocks the request.

When you see repeated retries, compare the first request with later attempts. Some providers resend the same event with the same idempotency key or event ID, while others include new delivery metadata each time. That difference matters when you are trying to identify duplicates.

How do replay and forwarding features help with webhook inspection?

Request replay lets you resend the same captured event after a fix, which is useful for confirming that parsing, signature verification, and downstream processing now work. Request forwarding lets you mirror a live webhook to another endpoint so you can test changes without disrupting production handling. Both features make webhook inspection repeatable instead of guesswork.

These features are especially useful in a staging environment, where you can compare the original delivery with a replayed event and verify that your application behaves the same way after a code change.

Is it safe to inspect sensitive webhook payloads?

It can be safe, but only if you treat inspection as a security and privacy workflow. Sensitive webhook payloads may contain personal data, payment details, tokens, or internal identifiers, so the inspection tool should support masking, access control, retention limits, and HTTPS.

Best practices include:

Redact secrets and personal data in logs and shared screenshots
Restrict access to production payloads
Avoid forwarding sensitive events to tools you do not control
Store only the data you need for debugging

If a provider sends payment webhooks or other regulated data, confirm that your inspection process matches your organization’s security requirements.

How do you correlate webhook requests with application logs?

Correlation works best when you capture a request ID, event ID, or correlation ID at the moment the webhook arrives and write it to your application logs, job queue, and error tracking system. If the provider includes a delivery ID, store that too.

A reliable correlation workflow looks like this:

Capture the incoming webhook metadata.
Log the event ID, correlation ID, and endpoint path.
Include the same identifiers in downstream jobs or database records.
Search logs by those IDs when a delivery fails.
Compare the logged status with the raw request in your inspection tool.

This is one of the most effective ways to connect webhook inspection with observability and logging.

How is webhook inspection different from webhook testing?

Webhook inspection shows what your endpoint actually received; webhook testing checks whether your code behaves as expected; debugging explains why it failed. Inspection is often the first layer of webhook testing because it exposes the raw payload, headers, and retry behavior before you write assertions.

Unit tests can use inspection logs or captured fixtures to verify parsing logic and schema validation. Integration tests benefit from real payload inspection plus response verification, which helps you confirm that your app returns the right status code and processes the event correctly. End-to-end tests can use inspection to confirm webhook delivery, retry logic, and downstream effects in systems like Slack, Shopify, or Salesforce.

When you need automation, repeatable checks, and assertions, move from inspection to endpoint testing and delivery testing. Inspection still matters there as observability and logging for each run.

Best practices for webhook inspection

Use separate endpoints for development, staging, and production.
Keep raw request capture enabled so you can verify signatures against the original body.
Check Content-Type, User-Agent, X-Signature, and X-Hub-Signature-256 on suspicious deliveries.
Validate payloads with schema validation before processing downstream actions.
Use request replay and request forwarding to reproduce bugs safely.
Correlate each delivery with logs using a correlation ID or event ID.
Protect sensitive data with HTTPS, masking, access control, and retention limits.

FAQ and conclusion

How do you inspect a webhook request?
Use a webhook debugger or similar inspection tool to capture the full HTTP request: headers, body, method, timestamp, and delivery metadata. Compare the raw payload with what your app expects, then check the status code and any correlation ID or request ID that links the delivery to your logs.

How do you debug a webhook that is not firing?
First confirm the event actually exists at the provider. If it was sent but never reached you, check endpoint URL, firewall rules, local tunnel setup, DNS, and whether your app is listening on the correct route. If the webhook appears in inspection but not in your app, focus on routing, auth, and upstream filtering. For a refresher on the delivery model, see what is a webhook.

What causes webhook delivery failures?
Common causes include timeouts, non-2xx responses, invalid endpoints, rate limits, malformed payloads, and signature mismatches. Delivery can also fail when the receiver is down, the body is changed in transit, or the provider retries after repeated errors.

How do you verify a webhook signature, and what if it fails?
Recompute the signature from the exact raw request body using the shared secret and the provider’s documented HMAC algorithm, then compare it with the signature header. If verification fails, check for body parsing that changes whitespace or encoding, the wrong secret, clock skew when timestamps are part of the scheme, and header name mismatches. Review webhook security practices before loosening verification.

Is it safe to inspect sensitive webhook payloads?
Yes, if you treat inspection as a security and privacy workflow, not just a debugging convenience. Limit access, redact secrets and personal data in logs, encrypt stored payloads, and avoid forwarding sensitive events to shared environments unless you control the destination.

How do replay and forwarding help?
Request replay lets you resend the same captured event after a fix, which is useful for confirming that parsing, signature verification, and downstream processing now work. Request forwarding lets you mirror a live webhook to another endpoint so you can test changes without disrupting production handling. Both features make webhook inspection repeatable instead of guesswork.

The best workflow is simple: inspect, validate, correlate, replay, and document. Inspect the raw request, validate headers and HMAC signature verification, correlate the event with application logs using a correlation ID, replay the delivery after fixes, and document what changed so the same failure is easier to spot next time.

Webhook Inspection: How to Debug and Test Webhooks