Webhook Testing Tool

Free — GPL coresize Mplanned, not built

Generated from docs/plan/core/webhook-testing-tool/PLAN.md in the AstroBaaS repository. Nothing described below is implemented — it is the written plan for it.

A local webhook testing proxy that intercepts webhook calls before they leave the server, allows request/response inspection, event replay with modified payloads, and simulates failure scenarios. Developers test webhook handlers against AstroBaaS without deploying to production.

The problem

Developers can’t test webhooks locally; they deploy to production to debug. Webhook bugs affect real customers: orders fail silently, inventory desynchronizes, and merchants have no way to know what went wrong.

What it does

• HTTP proxy that intercepts webhook dispatch before delivery to external URL
• Request/response inspection UI with full headers and body content
• Event replay with payload editor (modify and re-send captured events)
• Webhook URL override to redirect calls to localhost/test port
• Mock webhook response options (force success, simulate 5xx, timeout)
• Request history with filtering by event type and timestamp
• Timing and latency simulation (delay webhook response by N ms)
• Webhook signature validation on replayed events (HMAC check)
• Test mode toggle (on/off without restart)
• Session-only in-memory storage (no database persistence needed)

What it deliberately does NOT do

Each boundary carries its reason. A boundary without a reason gets crossed by the next person who reads this.

• Distributed webhook testing across multiple machines (reason: adds infrastructure; single-machine testing is sufficient for core development)
• Webhook retry/backoff logic testing (reason: belongs to paid integration suites with specific provider retry contracts)
• Load/stress testing webhooks (reason: specialized tool; core provides single-request inspection only)
• Webhook batching simulation (reason: specific to advanced integrations; first pass handles single events)

Data model

none

API

• GET /admin/webhooks/test/events
• POST /admin/webhooks/test/replay
• DELETE /admin/webhooks/test/events/:id
• DELETE /admin/webhooks/test/events
• GET /admin/webhooks/test/config
• PATCH /admin/webhooks/test/config

Every route added here must also appear in src/pages/openapi.json.ts — a test fails the build if it does not.

Admin

Webhook testing page showing real-time event interception. Inspector displays headers, body, timestamp, and response code. Replay button opens payload editor. ‘Fail next 3 calls’ toggle simulates transient failures. Clear history button. Test mode indicator (green/off state).

The seam — why this is core

Core owns the webhook dispatch mechanism and the test proxy hook injection point. Core provides request capture middleware. Testing tool is developer infrastructure, not a per-country obligation or support commitment.

Core owns the interface + honest webhook tester; development infrastructure is infrastructure, not a per-country obligation or credential.

Dependencies

• Existing webhook system (must be present)
• Admin UI framework
• Request middleware hooks

Acceptance checks

Each of these must be able to fail. Before claiming this is done, break the code deliberately and watch each one go red.

• A webhook event triggered in development is captured before leaving the webhook processor and does not reach the external URL
• An intercepted event can be replayed with modified payload without re-triggering the original action
• Webhook signature validation fails on a modified payload (signature correctly invalidated after edit)
• Test mode can be toggled on/off without restarting the app
• Captured events include full headers and body (not truncated; tested with 10KB payload)
• Event history persists across multiple webhook calls in a single session
• A webhook that fails during test can be replayed with ‘force success’ response override

Risks

If test mode is left enabled in production, all webhooks are captured and leaked. If replay doesn’t preserve event ordering, integrations that depend on order fail silently. If signature bypass is exposed carelessly, developers learn to ignore signature validation in production code.

Commercial context

The anchor is what the nearest equivalent charges on Shopify or Magento today. It is context for a pricing decision, not the decision.

---

Generated from the commerce plan. See docs/COMMERCE-PLAN.md for the full catalogue and ../../AI-GUIDE.md for how to work on this repository.