Webhook Testing and Debugging Guide: Inspect Signatures, Retries, Payloads, and Local Tunnels
webhooksAPI debuggingbackend developmentevent-driven architecturesignature verificationidempotency

Webhook Testing and Debugging Guide: Inspect Signatures, Retries, Payloads, and Local Tunnels

FFunction Forge Editorial Team
2026-11-21
8 min read

A practical webhook debugging workflow for signatures, retries, duplicates, payloads, local tunnels, replays, and delivery logs.

Webhook failures are often difficult to diagnose because the sender, network, tunnel, application, queue, and downstream service each leave different evidence. This webhook testing and debugging guide provides a repeatable workflow for capturing requests, checking payloads and signatures, exposing local endpoints, understanding retries, replaying events safely, and comparing provider delivery logs with your own application logs.

Overview

A webhook is an HTTP request triggered by an event in another system. The receiving application must accept the request, authenticate it, parse its body, process it, and return an appropriate response within the sender's delivery window. A problem at any stage can appear as a generic “webhook failed” message.

Start debugging by separating the delivery path into checkpoints:

  1. Provider: Was the event created and queued for delivery?
  2. Network: Could the provider resolve and connect to the endpoint?
  3. HTTP endpoint: Did the application receive the request and return a response?
  4. Verification: Did the signature, secret, timestamp, and event format pass validation?
  5. Processing: Did the handler complete its work, or did a downstream dependency fail?
  6. Persistence: Was the event recorded so that retries and duplicates can be handled safely?

This sequence prevents a common mistake: changing application code when the request never reached the server, or investigating a tunnel when the provider actually rejected the signature. For repeatable API debugging, pair webhook logs with a request tool such as this curl API testing guide and use the HTTP status code guide to classify responses.

What to track

Capture the complete request

During testing, record the HTTP method, full path, query string, relevant headers, raw request body, received time, response status, response body, and processing duration. Preserve the raw body before parsing JSON. Many signature schemes calculate a digest over the exact bytes received, so re-serializing a parsed object can produce a different value.

Do not log secrets, authorization values, or unnecessary personal data. Redact sensitive fields while retaining enough structure to compare a failed request with a successful one. A temporary request inspector or local endpoint can help you see whether a provider is sending the headers and content type you expect.

Track identifiers across every system

Capture the provider's event ID, delivery or attempt ID when available, your request ID, and any internal job or transaction ID. These identifiers allow you to match one event across provider dashboards, reverse proxies, application logs, queues, and databases. If the provider does not supply a stable identifier, derive a safe diagnostic key from the event type and a controlled subset of fields; do not use a full sensitive payload as a log key.

Monitor signature verification details

For each verification attempt, record a structured result such as missing_header, timestamp_outside_window, malformed_signature, secret_mismatch, or valid. Keep the secret itself out of logs. Check the provider's required signing input carefully: it may include a timestamp, a delimiter, a version marker, or the raw body. A correct HMAC algorithm with the wrong input will still fail.

When testing webhook signature verification, compare these values in a controlled environment:

  • the exact raw request bytes;
  • the configured secret and environment;
  • the algorithm and digest encoding;
  • the timestamp source and accepted clock-skew window;
  • the complete signature header, including any version or prefix;
  • constant-time comparison behavior in production code.

Track timing and delivery state

Record when the event was generated, when each attempt began, when your endpoint received it, when processing finished, and when the response was returned. Distinguish connection failures, timeouts, non-success HTTP responses, successful acknowledgments, and application-level failures. A provider's terms such as “delivered,” “accepted,” or “processed” may refer to different checkpoints, so compare the provider's definition with your own logs.

Use an idempotency record

Store a durable record for each accepted event before performing an operation that must not happen twice. The record can include the event ID, event type, first-seen time, processing state, attempt count, completion time, and a reference to the resulting business operation. Enforce uniqueness at the database layer when possible. An in-memory set is useful for a quick local test but is not sufficient across processes, restarts, or multiple instances.

Cadence and checkpoints

Webhook behavior should be checked at integration time, before release, after infrastructure changes, and on a recurring monthly or quarterly schedule. The exact cadence depends on event volume and operational risk, but a small review prevents an endpoint from silently drifting out of alignment with its provider.

First integration checkpoint

Begin with a controlled test event. Send it to a request inspector or a local endpoint exposed through a secure tunnel. Confirm the method, path, content type, headers, body encoding, signature input, and event identifier. Then send the same event through your actual handler and verify that it returns a fast acknowledgment without exposing secrets or dumping the complete payload into logs.

Pre-release checkpoint

Test valid events, malformed JSON, missing signature headers, invalid signatures, stale timestamps, unknown event types, duplicate deliveries, slow downstream dependencies, and provider retries. Confirm that expected failures produce useful status codes and that transient failures do not create a permanent data loss path.

If the endpoint is running locally, use a tunnel only for development and avoid treating an ad hoc public URL as a production endpoint. Check that the tunnel forwards the correct path, preserves required headers, remains reachable, and points to the intended local process. The same local workflow can be used with a browser-based request inspector, a command-line client, or a test fixture.

Monthly or quarterly operational review

  • Compare provider delivery failures with your HTTP access logs.
  • Review timeout rates, response classes, and processing duration.
  • Check whether duplicate events are being recognized rather than reprocessed.
  • Confirm that signature secrets and endpoint configuration match the intended environment.
  • Inspect dead-letter, retry, or unresolved-event queues.
  • Run one safe replay in a non-production environment, or use a production replay path with side effects disabled.
  • Verify that dashboards and alerts still identify the event and delivery attempt.

Provider-change checkpoint

Repeat the verification workflow whenever a provider changes event versions, signing algorithms, retry behavior, delivery-status terminology, payload fields, or endpoint requirements. This is also a good time to review tunnel instructions and test fixtures. Provider-specific details should be checked against the provider's current documentation rather than copied indefinitely from an old integration example.

How to interpret changes

Use the following table to narrow the fault domain before changing code:

ObservationLikely area to inspectNext action
No provider delivery attemptEvent selection, subscription, or provider-side queueConfirm the event was generated and the endpoint is subscribed to that event type.
DNS, connection, or TLS failureEndpoint reachability or certificate configurationCheck the public URL, DNS, firewall, certificate, and network policy.
Request appears in tunnel but not application logsLocal forwarding, route, proxy, or process configurationVerify the forwarded path, port, method, and application routing.
401, 403, or signature errorSecret, raw body, timestamp, or header parsingCompare the exact signing input and environment configuration; never disable verification as a permanent fix.
400 or parsing errorSchema, content type, or body handlingSave a redacted raw sample and compare it with the parser's expected format.
5xx or timeoutHandler, dependency, queue, or databaseReturn promptly after durable acceptance where appropriate, then process work asynchronously.
Many duplicate eventsRetry response, slow acknowledgment, or missing idempotencyRecord the event ID atomically and make repeated processing a no-op.
Provider says delivered, application says missingLogging, routing, proxy, or environment mismatchMatch delivery and request IDs, then verify that both systems refer to the same endpoint and time window.

Replaying an event safely

Replay should reproduce the original request closely, but it should not accidentally repeat an irreversible action. Use a non-production environment when possible. Otherwise, add a dry-run flag, isolate the event, or replace side-effecting integrations with test doubles. A replay record can follow this pattern:

{
  "sourceEventId": "provider-event-id",
  "sourceDeliveryId": "delivery-attempt-id",
  "receivedAt": "2026-01-15T10:20:30Z",
  "targetEnvironment": "staging",
  "dryRun": true,
  "signatureVerified": true,
  "originalStatus": 500,
  "replayReason": "handler timeout",
  "expectedSideEffects": ["update test record", "enqueue test job"]
}

Keep the original payload separate from replay metadata, and document whether the replay uses the original signature or a test-specific signature. Never paste production secrets into a local script or commit captured payloads to a repository.

Idempotency review checklist

  • Is there a stable event or delivery identifier?
  • Is uniqueness enforced durably rather than only in application memory?
  • Does the handler record “received,” “processing,” and “completed” states?
  • What happens if the process stops between the database write and the external side effect?
  • Can a retry safely resume or detect an already-completed operation?
  • Are event ordering assumptions explicit?
  • Can an operator replay one event without replaying an entire batch?

For tests around handlers, mocks, timers, and browser or server globals, a focused test suite can complement live delivery checks. The Vitest mocking and spies guide is useful when building those repeatable cases.

When to revisit

Revisit this webhook testing guide monthly or quarterly, and immediately after a change that could affect delivery or verification. The most important triggers are a provider API or event-version change, a new signing algorithm or secret rotation, a change to retry or timeout behavior, a new reverse proxy or tunnel, a deployment platform migration, or a change to queues and downstream services.

Use a short review record with the date, provider, endpoint environment, event types tested, signature result, response time, retry behavior, duplicate-handling result, and unresolved findings. If delivery failures rise, compare the provider's attempt timeline with your request and application logs before changing the handler. If failures fall after a fix, retain the test case that reproduced the original problem so a future deployment can run it again.

For a practical next step, choose one representative event and complete this sequence:

  1. Capture the request in a safe test environment.
  2. Store the raw body and redact sensitive values.
  3. Verify the signature using the exact received bytes.
  4. Return the expected acknowledgment and record the delivery identifiers.
  5. Replay the event with side effects disabled.
  6. Send it twice and confirm the second delivery is harmless.
  7. Compare provider, proxy, application, queue, and database records.

Keeping these checkpoints in a runbook turns webhook debugging from guesswork into an observable workflow. It also gives future maintainers a safe way to test integrations when events are delayed, rejected, duplicated, or missing.

Related Topics

#webhooks#API debugging#backend development#event-driven architecture#signature verification#idempotency
F

Function Forge 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.