Webhook Testing and Replay Guide: Inspect Payloads, Verify Signatures, and Reproduce Failures
webhooksAPIsbackend developmentrequest testingsecuritydebugging

Webhook Testing and Replay Guide: Inspect Payloads, Verify Signatures, and Reproduce Failures

WWebbClass Editorial Team
2026-11-17
7 min read

A practical webhook testing checklist for local inspection, signature verification, safe replay, retries, timeouts, and idempotent processing.

Testing a webhook is more than confirming that one request arrived. This guide provides a reusable workflow for exposing a local endpoint, inspecting headers and payloads, verifying signatures, replaying sanitized requests, testing retries and timeouts, and confirming that your handler processes duplicate deliveries safely.

Overview

A webhook integration connects an event producer to an HTTP endpoint that your application controls. When something happens—such as a payment update, repository change, form submission, or account event—the producer sends a request to your endpoint. Your application must receive it, authenticate it, validate its shape, perform the intended work, and return an appropriate response.

Failures can occur at several points. A local server may not be reachable from the public internet. A reverse proxy may rewrite or remove headers. A signature check may fail because the raw request body was parsed before verification. Your handler may return a success response before durable processing is complete, or it may perform the same operation twice when the sender retries. Effective webhook testing separates these concerns instead of treating the integration as a single pass-or-fail check.

Use this sequence as a baseline:

  1. Expose a controlled local or test endpoint.
  2. Capture the complete request, including method, URL, headers, and raw body.
  3. Compare the request with the provider's expected format.
  4. Verify authentication and signatures using the exact bytes received.
  5. Replay a sanitized fixture against a disposable environment.
  6. Test success, failure, timeout, retry, duplicate, and malformed-input cases.
  7. Record the result so the test can become a repeatable regression check.

Checklist by scenario

Testing a webhook locally

  • Run the application on a dedicated local port and confirm that the route works with a direct request.
  • Use a tunneling service or another controlled network path to give the sender a reachable HTTPS URL.
  • Forward only the required route rather than exposing unrelated development services.
  • Keep the tunnel URL, access token, and test endpoint separate from production credentials.
  • Check that the forwarded method, query string, headers, content type, and body arrive unchanged.
  • Close the tunnel when testing is complete and remove temporary access credentials.

Inspecting a request

A webhook request inspector is useful for answering basic questions before you inspect application code. Capture at least:

  • HTTP method and complete path
  • Timestamp of receipt and any provider event or delivery ID
  • Content type and content length
  • Signature, timestamp, authorization, and idempotency headers
  • Raw request body before JSON parsing or normalization
  • Response status, response headers, and elapsed time

Do not copy production secrets into a public inspector. Redact authorization values, signing secrets, personal data, payment information, and tokens before saving or sharing a capture.

Verifying a webhook signature

  1. Identify the provider's signing scheme and the exact header or headers involved.
  2. Confirm whether the signed input includes only the body or also a timestamp, version prefix, or event identifier.
  3. Read the body as raw bytes before a framework converts it to an object.
  4. Compute the expected value with the test secret and the documented algorithm.
  5. Compare values using a constant-time comparison where your language provides one.
  6. Apply an appropriate timestamp or replay check if the scheme includes one.
  7. Reject invalid requests before performing side effects, while returning the response behavior expected by the sender.

Never assume that parsing and serializing JSON produces the same signed content. Whitespace, property order, escaping, and line endings can change the bytes even when the data appears equivalent.

Replaying a captured request

Replay only a sanitized request in a test or staging environment. Preserve the original method, path, content type, and representative payload shape. Generate a new signature when the endpoint requires authentication; replaying an old signature may correctly fail because the timestamp or body no longer matches.

Use replay to answer one question at a time: does the parser accept the payload, does signature verification pass, does the handler create the expected record, or does the system remain safe when the same delivery arrives again?

Comparing common tool categories

Tool categoryBest useCheck before adopting
Request inspectorView incoming headers and bodies during developmentRetention, redaction, access controls, and supported methods
Secure tunnelRoute a provider's request to a local endpointHTTPS behavior, authentication, URL stability, and route restrictions
Provider test consoleTrigger documented sample events or deliveriesAvailable event types, test credentials, and retry controls
CLI or HTTP clientReplay fixtures and automate regression casesRaw-body handling, header support, and secret management
Application logsTrace receipt through validation and processingCorrelation IDs, sensitive-data filtering, and useful timing fields

Provider-agnostic test matrix

CaseExpected behavior
Valid new eventAuthenticate, validate, process once, and return the expected success response.
Duplicate eventRecognize the delivery or event ID and avoid repeating the side effect.
Invalid signatureReject before business processing and log a safe diagnostic.
Malformed JSONReturn a controlled client error without crashing the worker or server.
Unknown event typeHandle deliberately: ignore, record, or reject according to the integration contract.
Slow downstream serviceApply a defined timeout and avoid holding the webhook request indefinitely.
Temporary server failureReturn a failure response when appropriate so the sender can retry, or queue work for safe recovery.
Out-of-order deliveryUse event timestamps or state checks rather than assuming arrival order.

Safe payload fixture

Keep a small fixture in your test suite with fake identifiers and non-sensitive values. Adapt the fields to the provider's schema:

{
  "id": "evt_test_001",
  "type": "resource.updated",
  "created_at": "2025-01-15T12:00:00Z",
  "data": {
    "id": "resource_test_001",
    "status": "active"
  },
  "delivery_id": "delivery_test_001"
}

Store the expected response and processing result alongside the fixture. If signature verification is part of the test, document which fields are signed and generate the signature during the test rather than committing a real secret.

What to double-check

  • Raw body access: Confirm that middleware has not parsed, transformed, or compressed the body before signature verification.
  • Clock handling: If signatures contain timestamps, verify the server clock and define how old a request may be before rejection.
  • Idempotency: Use a durable event or delivery identifier when available. A process-local memory flag is not sufficient after a restart or across multiple workers.
  • Response timing: Separate quick receipt acknowledgment from longer business processing when the provider expects a prompt response.
  • Retry behavior: Record how your endpoint responds to timeouts and different status classes. Provider retry schedules can vary and should be checked in the relevant documentation.
  • Content limits: Test realistic body sizes, nested data, empty values, and unexpected additional fields.
  • Observability: Log a correlation or delivery ID, validation result, processing status, and duration without logging secrets or full personal records.
  • Environment boundaries: Make sure test events cannot reach production resources through shared queues, databases, credentials, or callback URLs.

If the payload is complex, validate it against a versioned schema. A JSON Schema validation workflow can help distinguish a missing required field from a signature or transport problem; see the JSON Schema Validation Tools guide.

Common mistakes

  • Testing only the happy path: A successful sample does not reveal duplicate processing, malformed input, timeout behavior, or out-of-order events.
  • Using a public tunnel without restrictions: A development endpoint may expose debug pages or accept arbitrary requests. Limit routes and authentication, and shut it down after use.
  • Verifying a parsed object: Signature algorithms generally operate on the received representation, not an equivalent object reconstructed by your framework.
  • Returning success after a partial failure: A success response should reflect a deliberate processing state. Otherwise, a sender may stop retrying while your system has lost the event.
  • Assuming one delivery equals one event: Network interruptions can cause a sender or client to retry. Make side effects idempotent.
  • Saving sensitive captures indefinitely: Treat request logs and inspector records as potentially sensitive data. Set retention rules and redact before sharing.
  • Changing the payload during replay: A manually edited body may test parsing but no longer reproduce the original failure. Keep an untouched capture and a separately named modified fixture.

For broader API debugging, also check whether a browser-origin request is being affected by CORS or preflight behavior; the CORS troubleshooting guide covers that separate failure path.

When to revisit

Return to this checklist whenever you add a provider, change a webhook route, rotate signing credentials, upgrade a framework, or modify request middleware. It is especially useful after changing queueing, database, authentication, or deployment infrastructure because those changes can affect acknowledgment timing and duplicate handling.

Before a seasonal planning cycle or another period of expected traffic, rerun the fixture matrix and confirm that logs, alerts, queues, and dead-letter handling still provide enough information to investigate a missed delivery. When a provider changes its API version, event schema, signing scheme, retry behavior, or supported request features, update the fixtures and this test record rather than relying on an old capture.

For a practical incident response, work through these steps:

  1. Find the provider's delivery ID and timestamp.
  2. Confirm whether the request reached the tunnel, load balancer, application, and queue.
  3. Compare the received status and response time with the sender's delivery record.
  4. Check signature verification separately from payload validation.
  5. Determine whether the event was rejected, accepted but unprocessed, or processed more than once.
  6. Replay a redacted fixture in a safe environment and record the result.
  7. Only then decide whether the cause is the sender, network path, or receiving application.

Keep the final test matrix, sanitized fixtures, endpoint contract, and update date together in the project repository. That small record turns webhook debugging from an improvised investigation into a repeatable developer tool workflow.

Related Topics

#webhooks#APIs#backend development#request testing#security#debugging
W

WebbClass Editorial Team

Developer Tools Editor

Senior editor and content strategist. Writing about technology, design, and the future of digital media. Follow along for deep dives into the industry's moving parts.