Test Incoming Webhooks: Verify Your Endpoints Work Correctly

Ever shipped a webhook that silently failed in production?
You thought it worked locally, but the sender never saw a proper 200 or the signature check rejected the payload.
Testing incoming webhooks doesn’t need a redeploy to staging or guesswork.
This guide shows a repeatable, end-to-end workflow to capture real payloads, run and expose a local endpoint with a tunnel, verify headers and signatures, and confirm correct response codes and retry behavior before you hit production.

Practical Methods to Test Incoming Webhooks Effectively

Testing incoming webhooks needs a repeatable workflow that catches real integration issues before you ship. You’re trying to verify that your endpoint receives payloads, parses them right, enforces security checks, and returns status codes that keep the sender happy.

The problem is simple: webhook senders want a publicly accessible HTTPS URL. Your local dev server at localhost:3000 is invisible to the outside world. You need to bridge that gap without redeploying to staging after every single code change.

Most testing workflows look pretty similar. Capture a payload to understand structure and headers. Build or update your local endpoint to handle it. Expose your local server through a public URL. Register that URL with the sending platform. Trigger a test event. Inspect what arrived. Verify your response matches expectations. Iterate when things break.

Public request bins and tunneling tools do the heavy lifting here. Bins let you see exactly what a sender transmits, but anyone with the URL can view your data. Private bins need an account and protect sensitive stuff. Tunneling routes live traffic to your localhost, so you get real-time debugging and instant feedback.

Here’s the complete end-to-end process:

1. Capture the payload structure by sending a webhook to a request bin. Check headers, body schema, signature headers, Content-Type.
2. Build a local endpoint that logs the full request, validates JSON or form-encoded data, and returns a 2xx status.
3. Expose your local server using a tunneling tool that forwards requests from a public URL to your localhost port (usually 80 or 3000).
4. Register the public tunnel URL in the sending platform’s webhook config and enable the event types you want.
5. Trigger test events using the platform’s test feature, then check the logs and captured data in your endpoint or the tunnel dashboard.
6. Verify responses and retries by confirming your endpoint returned the right status code, the sender logged successful delivery, and retry logic works as documented.

Tools and Utilities for Incoming Webhook Testing

Developers testing incoming webhooks rely on two categories of tools. Request inspection services and tunneling utilities. Inspection services capture HTTP requests at a public URL and show headers, bodies, and metadata in a web UI. Tunneling routes live traffic from a public endpoint to your local machine so you can test and debug your actual code in real time.

RequestBin and Webhook.site are popular inspection services. Both generate a unique public URL and display every incoming request in a browser dashboard with raw headers, payloads, and timing. RequestBin offers public and private bins (private needs an account). Webhook.site gives you immediate no-signup access but URLs are discoverable. These are great for understanding what a sender transmits before you write any code.

Tunneling tools handle the next step: connecting external traffic to your local environment. Core differences:

ngrok needs a free account and authtoken. Provides stable public URLs and detailed traffic inspection. Supports custom domains and reserved subdomains on paid plans. Most widely adopted tool for webhook testing.

Localtunnel is open-source, no account needed, requires Node.js. Generates random public URLs. Good for quick one-off tests where URL persistence doesn’t matter.

Pagekite requires Python 3.x. First run prompts for email and account creation. Uses a name-based subdomain pattern (yourname.pagekite.me). Less common but useful in environments where Node.js isn’t available.

Expose is a commercial tool with a free tier. Opens a secure 2-way tunnel. Provides a local dashboard at 127.0.0.1:8080 for inspecting incoming requests and supports one-click replay. Pro tier includes reserved subdomains, custom domains, and automatic SSL.

Built-in platform features: Laravel Valet includes valet share (wraps ngrok), and Local by Flywheel offers Live Links for WordPress sites with HTTP Basic auth protection.

Setting Up a Local Endpoint to Receive Webhooks

A local webhook endpoint is just a simple HTTP server that listens for POST (or GET) requests, logs the incoming data, validates the payload, and returns a status code. The endpoint runs on a port your tunneling tool can access (typically 80 or 3000) and handles whatever Content-Type the sender uses (usually application/json or application/x-www-form-urlencoded).

You can build a webhook listener in any language. A Node.js Express route on port 3000 might parse JSON bodies, log request headers and the parsed object, verify a signature header if needed, and respond with 200 OK. A Python Flask route does the same thing: define a POST handler, access request.headers and request.json, print or save the data, check signatures, return a status tuple. A Go HTTP handler reads the request body with io.ReadAll, unmarshals JSON, logs the result, validates HMAC if present, writes a 200 response.

Every test endpoint should:

Log all headers to verify the sender includes expected authentication, signature, or timestamp headers (like X-Hub-Signature, Stripe-Signature, Authorization).

Validate and parse the body to confirm JSON structure, required fields, and data types. Log parse errors for debugging.

Return precise HTTP status codes that match the sender’s expectations. 2xx for success, 4xx for client errors, 5xx for server errors. Incorrect codes trigger unnecessary retries or halt delivery.

Print or store signature headers separately to test HMAC or secret-based verification without modifying the payload.

When testing locally, simulate real payloads using captured JSON files and replay them with curl or Postman to verify endpoint behavior before exposing it publicly. This inner loop catches parsing bugs, missing fields, and incorrect status logic before live traffic shows up.

Exposing Local Webhook Endpoints to the Internet

Once your local endpoint runs and handles mock payloads, you need a public URL that routes traffic to your machine. Tunneling tools create this bridge by opening an outbound connection from your localhost to a remote server, which then forwards incoming HTTP requests back through that tunnel.

ngrok is the most common tunneling tool and needs a free account. After signing up, download the binary, extract it, and add your authtoken by running the command from your account dashboard. To expose a server on port 80, execute ngrok http 80 and ngrok prints a public HTTPS URL (format: subdomain.ngrok.io) that forwards to localhost:80. The ngrok web interface at 127.0.0.1:4040 displays incoming requests, headers, bodies, and response details in real time.

Localtunnel is an open-source alternative that requires Node.js. Install the CLI globally, then run a command to expose a local port using a subdomain pattern. Pagekite requires Python 3.x. Fetch the pagekite.py script, create a “kite” with a unique name identifier, and the tool prompts for email and account creation on first run. Expose uses commands like expose share http://localhost and provides a local dashboard at 127.0.0.1:8080 for inspecting and replaying requests. Pro users get reserved subdomains and custom domain support with automatic SSL.

Here’s the workflow to expose your local endpoint:

1. Start your local webhook server on a known port (usually 80 or 3000) and confirm it responds to test requests from curl or your browser.
2. Launch your tunneling tool with the right command and port argument. Make sure any required authtoken or account setup is complete.
3. Copy the public HTTPS URL from the tool’s console output. This is the URL you’ll register with the sending platform.
4. If your local server uses virtual hosts (like Laravel Valet with a .test domain), configure the tunnel to rewrite the Host header so your web server serves the correct site. ngrok and Expose both support Host header options.
5. Verify the tunnel by visiting the public URL in a browser or sending a test POST request with curl. Check that the request reaches your local logs and the response returns correctly.

Platform-Specific Incoming Webhook Testing (Stripe, GitHub, Slack)

Major platforms provide built-in tools to send test events and verify your webhook endpoint without waiting for real user activity. These features speed up development by letting you trigger specific event types on demand and inspect the exact payloads your endpoint receives in production.

Stripe Test Events and Signature Validation

Stripe’s webhook dashboard includes a “Send test webhook” button that fires synthetic events (like payment_intent.succeeded, invoice.paid) to your registered endpoint. Each test event includes a Stripe-Signature header containing a timestamp and HMAC-SHA256 signature computed from your webhook signing secret. Your endpoint extracts the signature, recomputes the HMAC using the raw request body and your secret, compares the result, and verifies the timestamp is recent (usually within 5 minutes) to reject replay attacks. Stripe provides libraries in multiple languages that handle signature verification automatically, but manual verification helps you understand the process during testing.

GitHub Delivery Tests and HMAC Verification

GitHub webhook settings include a “Recent Deliveries” tab that lists every sent event with full request and response details. Click any delivery to view headers, payload JSON, and your endpoint’s response code and body. GitHub also supports re-sending any past event by clicking “Redeliver,” which sends an identical payload and resets the delivery attempt counter. GitHub’s X-Hub-Signature-256 header contains an HMAC-SHA256 signature computed from your secret and the request body. Your endpoint recomputes the signature and compares it byte-for-byte to verify authenticity.

Slack URL Verification and Event Simulation

Slack’s Event Subscriptions feature requires a URL verification handshake before enabling webhooks. When you save your endpoint URL, Slack sends a POST request with a challenge field in the JSON body. Your endpoint must immediately return a 200 response with the challenge value in plain text (not JSON-wrapped). Once verified, Slack sends event payloads with a token field that matches your app’s verification token. You should check this token in every request. Slack’s app dashboard includes a “Reinstall App” flow that re-triggers the URL verification, and you can simulate events using Slack’s testing tools or by triggering real actions in a test workspace.

Debugging, Logging, and Inspecting Incoming Webhook Requests

When a webhook test fails or behaves unexpectedly, detailed logs and request inspection tools pinpoint the issue. The most common problems? Missing headers, malformed payloads, incorrect status codes, and signature mismatches. All of which require comparing what you expected against what actually arrived.

Capture the full request by logging raw headers and the unparsed body before any processing. Many frameworks automatically parse JSON or form data, which hides encoding issues and trailing whitespace that break signature verification. Print the Content-Type header to confirm the sender’s format matches your parser. Log the response status code you return and compare it to the sender’s delivery logs to verify both sides agree on success or failure.

Tunneling dashboards are invaluable for live debugging. ngrok’s web interface at 127.0.0.1:4040 shows every request with expandable headers and body views, plus your response details and timing. Expose’s dashboard at 127.0.0.1:8080 adds one-click replay, letting you resend the exact same request to your local endpoint without re-triggering the event in the sending platform. Request bins display the sender’s perspective, showing what was transmitted before your endpoint modified or rejected it.

Common debugging techniques:

Compare expected vs received payloads by saving a known-good example from the platform’s docs and diffing it against your logged data.

Check response timing to ensure your endpoint responds within the sender’s timeout window (often 5 to 30 seconds).

Inspect retry attempts in the sender’s delivery log to verify your non-2xx responses triggered retries and your corrected endpoint eventually returned 200.

Use correlation or request IDs provided by the sender (like GitHub’s X-GitHub-Delivery, Stripe’s event ID) to trace a single webhook through logs, dashboards, and external monitoring.

Security Validation When Testing Incoming Webhooks

Webhook endpoints are public URLs that accept POST requests from anywhere, so security validation is critical to prevent unauthorized or tampered payloads from reaching your application logic. Testing must verify that your endpoint enforces authentication, signature checks, and replay protections consistently.

Signature verification is the most common security pattern. The sender computes an HMAC signature using a shared secret and includes it in a header. Your endpoint recomputes the signature from the raw request body and the same secret, then compares the two. A mismatch means tampering or an incorrect secret, and your endpoint should reject the request with 401 or 403. Stripe, GitHub, and Twilio all use HMAC-SHA256. Slack uses a verification token in the payload.

Some platforms require HTTP Basic Authentication or Bearer tokens in the Authorization header. Test these by sending requests with missing, malformed, or incorrect credentials and verifying your endpoint returns 401 Unauthorized. If your endpoint sits behind a reverse proxy or API gateway, confirm the proxy forwards authentication headers and doesn’t strip them.

Five critical security tests for incoming webhooks:

1. HMAC signature verification: Send a valid payload with a correct signature and confirm 200 OK. Resend with a modified body or wrong secret and verify 401 or 403.
2. Timestamp skew handling: Include a timestamp in the signature computation (if supported) and reject requests with timestamps outside a 5-minute window to block replay attacks.
3. Bearer token or API key validation: Test requests with valid, missing, and invalid tokens. Ensure only valid tokens return 2xx and invalid tokens return 401.
4. HTTPS enforcement: Reject or ignore webhooks sent over plain HTTP to prevent credential and payload interception (tunneling tools provide HTTPS by default).
5. Replay protection: Log a unique event ID or request ID from the sender and reject duplicate IDs to prevent processing the same event multiple times if a retry occurs.

Testing Retries, Failures, and Non‑2xx Responses for Incoming Webhooks

Webhook senders retry failed deliveries using exponential backoff, but retry policies vary widely. Stripe retries for up to 3 days, GitHub retries for 1 hour with 5 attempts, and Slack retries 3 times within minutes. Testing retry behavior ensures your endpoint handles transient failures gracefully and eventually processes every event.

Simulate failures by returning non-2xx status codes from your endpoint. A 500 Internal Server Error signals a temporary problem and most senders will retry. A 429 Too Many Requests with a Retry-After header tells the sender to wait before retrying. Client error codes like 400 Bad Request, 401 Unauthorized, or 404 Not Found usually halt retries because the sender assumes the problem is permanent. Test each code to verify the sender’s behavior matches your expectations.

Typical failure and retry cases to test:

Temporary outage (500): Return 500 from your endpoint, check the sender’s retry log, then fix the endpoint and verify the retry succeeds.

Rate limiting (429): Return 429 with Retry-After: 60 and confirm the sender waits approximately 60 seconds before retrying.

Authentication failure (401): Return 401, verify the sender stops retrying, fix the credentials, and confirm a manual resend or new event succeeds.

Endpoint not found (404): Intentionally register a wrong URL, verify retries stop quickly, correct the URL, and test a new event.

Timeout simulation: Add a 35-second sleep in your endpoint (if the sender’s timeout is 30 seconds), observe the timeout in the sender’s log, then remove the sleep and verify the next retry succeeds.

Replay tools in tunneling dashboards and sender UIs let you resend a failed event without waiting for the natural retry delay. Use replay to quickly iterate on fixes and confirm that the corrected endpoint processes the event on the first attempt.

Automating Incoming Webhook Tests with CI/CD

Automated webhook tests prevent regressions and verify that deployment or dependency changes don’t break payload parsing, signature validation, or retry logic. Continuous integration pipelines run tests on every commit, catching issues before they reach staging or production.

The most common approach? Capture representative payloads as JSON files in your repository and replay them in test environments. A CI workflow starts your application server, sends stored payloads via HTTP POST using curl or a test client, and asserts that the endpoint returns the correct status code and produces expected side effects (database writes, log entries, external API calls). Signature headers must be recomputed for each test run if your signing secret is environment-specific.

Postman collections define requests, headers, and assertions. Newman is the CLI runner that executes Postman collections in CI. A typical workflow exports a collection with webhook test cases, checks it into version control, and runs newman run collection.json in the CI pipeline. supertest is a Node.js library that makes HTTP requests to your app and asserts responses inline, ideal for integration tests that verify endpoint behavior without manual setup.

Synthetic monitoring complements CI tests by periodically sending webhook payloads to production or staging endpoints from external locations and alerting when responses fail or exceed latency thresholds. This catches infrastructure issues, network problems, and configuration drift that unit and integration tests miss.

Final Words

In the action: you captured payloads, exposed a local listener with tunneling tools, registered public URLs, sent test events, and inspected headers, bodies, and status codes.

You also walked through signature checks for Stripe/GitHub/Slack, replaying payloads, simulating failures and retries, and logging for quick debugging.

Now run the checklist and test incoming webhooks end-to-end in your staging environment. You’ll catch issues earlier and push changes with more confidence.

FAQ

Q: How do I test incoming webhooks end-to-end?

A: To test incoming webhooks end-to-end, capture payloads with a request bin or tunnel, expose your local listener, register the public URL, send test events, verify headers/body and 2xx responses, then replay and check retries.

Q: What tools can I use to capture and inspect webhook payloads?

A: To capture and inspect webhook payloads, use RequestBin or Webhook.site for quick captures, and ngrok, Localtunnel, Pagekite, or Expose to expose local ports and view raw requests in a dashboard.

Q: How do I set up a local endpoint to receive webhooks?

A: To set up a local endpoint, create a simple POST route (Express, Flask, Go), log headers/body/timing, validate JSON and signatures, return precise status codes, and replay payloads with curl or Postman for testing.

Q: How do I expose my local webhook endpoint to the internet?

A: To expose your local endpoint, start a tunnel (ngrok, Localtunnel, Pagekite, Expose), get the public URL, register it with the provider, and account for host header rewrites or virtual-host setups as needed.

Q: How do I test platform-specific webhooks (Stripe, GitHub, Slack)?

A: To test platform-specific webhooks, use each platform’s test or replay features: Stripe sends signed events with signature headers, GitHub uses X-Hub-Signature HMAC, and Slack requires URL verification and token checks.

Q: What should I log and inspect when debugging webhook requests?

A: When debugging webhook requests, log full headers, raw body, response status codes, timing, and correlation IDs; compare expected versus received payloads and verify signature headers and retry behavior.

Q: How do I validate webhook security and signatures?

A: To validate webhook security and signatures, verify HMAC signatures with your secret, check timestamps to prevent replay attacks, enforce HTTPS, and validate Basic or Bearer tokens and challenge flows.

Q: How do I test retry behavior and non-2xx responses?

A: To test retry behavior, simulate non-2xx responses (400, 401, 404, 429, 500), observe provider retry timing and Retry-After headers, ensure your handler is idempotent, and use replay tools to emulate retries.

Q: How can I automate webhook tests in CI/CD?

A: To automate webhook tests in CI/CD, replay captured JSON payloads using Postman/Newman or test libraries (supertest), run against staging endpoints in pipelines, and add synthetic monitors for ongoing checks.

Q: What’s the difference between public and private request bins?

A: The difference between public and private bins is that public bins are viewable by anyone, while private bins require an account and keep captured payloads restricted to authorized users.