Webhook Tester

Why Test Webhooks Synthetically

Webhooks are the most-likely-to-break part of many integrations. They're asynchronous, order-unstable, retried, signed in inconsistent ways, and shaped differently across providers, but every webhook handler has to be solid on production day one, because debugging a broken handler at 2am when real payments are failing is a bad day.

The way to avoid that is testing every code path before going live. Real provider events cover the happy path (a successful payment, a normal push). The interesting cases, disputes, refunds, subscription downgrades, failed deliveries, rate-limited retries, are harder to trigger. A webhook tester lets you craft exactly those payloads and run them through your handler.

Anatomy of a Webhook Test

A complete webhook test sends:

HTTP method. Almost always POST. A few providers use GET for verification handshakes (Facebook, LINE).

Headers. Content-Type (application/json for most, application/x-www-form-urlencoded for some, Twilio is form data, Slack mixes JSON and form). Provider-specific signature headers (Stripe-Signature, X-Hub-Signature-256, X-Shopify-Hmac-Sha256). User-Agent that mimics the provider.

Body. JSON or form-encoded data matching the provider's published event schema.

Common Provider Quirks

Stripe. Wraps every event in an Event object with type, id, created, data.object. The actual payload is in data.object. Signature is HMAC-SHA256 over the literal request body, with a timestamp prefix.

GitHub. Uses the X-GitHub-Event header to indicate event type (push, pull_request, issues). Same URL receives all event types. X-Hub-Signature-256 is the signed body.

Discord. Interaction payloads have a strict 3-second response window; if you don't ACK in time, the user sees an error. Signature uses Ed25519, not HMAC.

Shopify. API version is in the URL path. Sends X-Shopify-Topic for event type, X-Shopify-Hmac-Sha256 for signing. Body is base64-encoded for some events.

Slack. Mix of JSON and form-encoded. Events API uses JSON; slash commands and interactivity use form-encoded. Different signing scheme (X-Slack-Signature) from most.

Edge Cases Worth Testing

Missing fields. Send a payload with a required field omitted. Does your handler crash, or return a clean 400?

Extra unexpected fields. Send a payload with extra fields the provider hasn't documented. Your code should ignore them (forward compatibility).

Wrong types. Send a string where a number is expected, or null where an object is expected. Many handlers crash on this.

Large payloads. Some providers cap webhook payload size, some don't. Test with a 1MB payload. Does your handler buffer everything in memory, or stream?

Duplicate event IDs. Send the same event ID twice. Does your handler process the work twice (bad) or recognize the duplicate (good)?

Out-of-order events. Send an "order.refunded" before "order.created". Does your handler get confused, or handle the case gracefully?

Very old events. Stripe and others retry for up to 3 days. If a 2-day-old event arrives, does your handler accept it, or has the related state expired?

Building a Robust Handler

A robust webhook handler typically:

1. Verifies signature first. Reject unsigned requests with 401. Don't do any work, including logging the payload, before signature verification, because attackers may probe.
2. Returns 200 quickly. Acknowledge receipt as fast as possible. Queue work for async processing.
3. Uses idempotency keys. Store recent event IDs (with TTL) to skip duplicates.
4. Logs everything. Webhook bugs are notoriously hard to reproduce. Log raw payloads (carefully redacting PII) for at least a few days.
5. Handles unknown event types. Don't crash if a new event type arrives. Log and return 200.
6. Versions the handler. Provider changes their payload format? You need to keep handling old versions during the transition.

Workflows

1. Initial integration. Use presets to fire common events at your handler. Verify each is processed correctly.
2. Refactor verification. After changing webhook handler code, replay a suite of test payloads to verify behavior.
3. Edge-case design. When designing how to handle (e.g.) subscription cancellations, fire the relevant test events and observe behavior in your code.
4. Pre-production load test. Send 100 events in quick succession. Does your queue keep up? Are events processed in order, or do races cause issues?
5. Cross-environment verification. Replay the same payload against staging and production. Outputs should match.

When to Use This vs. a Webhook Inspector

• Tester (this tool): you control the payload, send to your handler, observe how your code reacts.
• Inspector: provider controls the payload, sends to a temporary URL, you observe what arrived.

Use the inspector first to learn what a provider's events look like. Use the tester to feed those payloads into your handler at will.

Common Mistakes

Hardcoding payload shapes from old docs. Providers update their schemas. A field that used to be a string is now an object. Test with current payloads.

Not testing the retry path. Providers retry on 5xx. If your code returns 5xx on a permanent failure, you'll get hammered. Always return 4xx for input you can't fix.

Forgetting about retries during deploys. A deploy that takes 30 seconds is fine for a website; it can mean dozens of webhook retries from a busy provider. Use a queue between the public endpoint and your processing code so deploys don't drop events.

No alerting on signature failures. If signatures start failing, either someone is attacking you or you've broken your verification code in a recent deploy. Alert on it.

Privacy

Payloads sent through the tester are dispatched from your browser to the URL you specify. Nothing is stored on the tool's side, useful when crafting test payloads that contain customer-like data.