Webhook debugging guides
Capture a real webhook, reproduce it on your machine, fix the handler and keep it fixed. Each guide covers one step with the commands to run.
Workflow
- Local webhook developmentReceive real webhooks on localhost with hwcli listen: no tunnel, the exact bytes and headers, signatures intact, and every delivery recorded.
- Replay a webhook locallySend a captured webhook to your local server again with hwcli replay or Replay Locally: same method, path, headers, signature and raw body.
- Modify and replay a webhookChange JSON fields, headers, query or method and replay a captured webhook without touching the original event. Side-by-side diff of every change.
- Debug production webhook failures locallyTake a webhook that failed in production, replay it against your local code in a Debug Session, fix the bug and keep the fix with a regression test.
Replay Lab
- Replay LabTurn one captured webhook into duplicate, concurrent, delayed, burst, unsigned or malformed deliveries to test how your handler behaves under real conditions.
- Testing duplicate webhooksProviders deliver the same event more than once. Replay one event several times and check your handler processes it exactly once.
- Testing webhook idempotencyUse duplicate and concurrent replays to find race conditions in webhook handlers and check idempotency keys actually work.
- Testing webhook signature validationCheck your handler rejects invalid and missing signatures and accepts valid ones, with test signatures generated from your stored signing secret.
- Testing out-of-order webhooksWebhooks don't arrive in the order events happened. Replay real events in a different sequence and check your state machine copes.
- Testing webhook retriesSimulate provider retries with delayed duplicate deliveries and check your handler's retry and timeout behavior.
Tests
- Create webhook regression testsSave a real webhook and the response your handler should give as a test, from the dashboard, a Debug Session or a YAML file.
- Run webhook tests in CI/CDRun your webhook regression tests in GitHub Actions, GitLab CI, Jenkins or Bitbucket with hwcli test run, JUnit reports and clear exit codes.
Analysis
- Compare failed and successful webhooksDiff a failed webhook against a successful one of the same type: changed values, missing fields, type changes and headers, with volatile fields hidden.
- Webhook schema drift detectionHookWatcher learns each event type's payload structure and reports when a provider adds, removes or changes the type of a field.
Providers
- Debug Stripe webhooks locallyReceive and replay Stripe webhooks on localhost, test Stripe-Signature validation with fresh test signatures and catch duplicate event handling bugs.
- Debug Shopify webhooks locallyReceive Shopify webhooks on localhost with the X-Shopify-Hmac-Sha256 header intact, replay orders and test duplicate and out-of-order deliveries.
Reference material, including the API and every hwcli command, is in the documentation.