Capturing, Validating, and Replaying Webhooks Locally with Webhook Reliability Kit

Webhooks are the connective tissue of modern web architectures. When a customer completes a checkout on Stripe, authenticates via an identity provider, or pushes code to GitHub, webhooks asynchronously notify your backend services so you can provision accounts, update databases, and trigger business workflows.

Despite their ubiquity, developing and testing webhook handlers remains one of the most frustrating tasks in backend engineering. Because webhooks originate from external third-party servers, local development traditionally requires setting up tunneling proxies (like ngrok), creating mock webhook endpoints, or repeatedly triggering real transactions in sandbox environments.

The Common Failure Modes of Webhook Integrations

In production systems, webhook failures typically stem from five recurring challenges:

• Cryptographic HMAC Mismatches: Incorrect signature hashing algorithms, mismatched secret keys, or failing to verify raw request byte streams before JSON parsing.
• Timestamp Tolerance & Replay Attacks: Providers like Stripe sign payloads with a timestamp (t=...,v1=...). Handlers that fail to validate timestamp freshness remain vulnerable to replay attacks.
• Retry Storms & Idempotency: When a recipient endpoint times out or returns a 500 error, providers retry aggressively. If the consumer lacks idempotent processing, duplicate charges or records occur.
• Payload Schema Drift: Providers periodically update payload structures, breaking consumers that assume static JSON formats.
• Local Debugging Blindspots: Developers cannot easily inspect raw incoming payloads, reproduce past failures, or test retry policies locally.

Architecture of Webhook Reliability Workbench

To solve these challenges without relying on external SaaS webhook proxies, I engineered and open-sourced Webhook Reliability Workbench (Webhook Reliability Kit). Designed as a local-first developer tool in TypeScript, it runs completely on your workstation.

The tool integrates several core subsystems:

• Local Ingestion Server: A fast HTTP receiver built on Fastify that captures incoming webhook requests on any configurable port.
• Multi-Vendor Signature Verifier: Validates cryptographic HMAC signatures using timing-safe comparisons across Stripe, GitHub, Shopify, and generic SHA-256/SHA-512 formats.
• Persistent Event Store: An append-only local file storage engine that records event IDs, timestamps, headers, and raw bodies for cross-session inspection.
• Fixture Exporter: Allows developers to export captured real-world payloads into clean, reusable JSON fixtures for automated regression testing.
• Safe Replay Engine: Replays captured events to local development endpoints with strict Server-Side Request Forgery (SSRF) protections.

Security Safeguards: SSRF Defense and Automatic Redaction

Replaying webhooks to arbitrary URLs presents severe security risks if misconfigured. The workbench implements DNS-level SSRF resolution checks, blocking loopback addresses, link-local addresses, and private cloud metadata endpoints (169.254.169.254) by default. Localhost replay is permitted only when developers explicitly provide the --allow-localhost flag.

Furthermore, the tool automatically redacts authorization headers, Bearer tokens, passwords, and sensitive keys (such as credit card numbers or secret tokens) in terminal outputs and JSON exports, ensuring zero accidental credential leakage.

Practical Developer Workflow

Using the workbench in daily development involves three simple steps:

# 1. Start the local listener with a signature secret
webhook-workbench listen --port 4000 --secret whsec_test_secret_123

# 2. Inspect captured events
webhook-workbench events list
webhook-workbench events inspect --id evt_01h8abc123

# 3. Safely replay the event to your local app handler
webhook-workbench replay --id evt_01h8abc123 --url http://127.0.0.1:3000/api/webhooks --allow-localhost

Verification and Automated Test Evidence

The workbench is backed by an automated Vitest test suite consisting of 8 test files and 83 passed tests. The tests verify cryptographic verifiers, replay execution, retry simulation with exponential backoff, persistent storage transactions, and SSRF loopback protections.

Limitations

Webhook Reliability Workbench is engineered specifically as a local developer tool and automated CI failure simulator. It is not designed to operate as a high-availability multi-tenant public proxy in production.

Project Resources

The repository is freely available under the MIT License on the Webhook Reliability Workbench GitHub Repository.

To see all seven verified open-source utilities, explore the Open-Source Projects Resource Hub. For assistance designing reliable, event-driven architectures and webhook integrations, see my Full-Stack Engineering services.