Skip to main content

Replay Cases

Replay cases turn captured webhook requests into repeatable integration tests. Save a useful request, add assertions for the response you expect, then replay one case or a suite of cases against a local CLI listener, staging URL, or production-like target.

When to use replay cases​

Use replay cases when you want to:

  • Re-run real webhook payloads after changing your handler
  • Build regression coverage from captured Stripe, GitHub, Shopify, or custom webhook examples
  • Compare how local and staging handlers respond to the same request
  • Share a stable case with a teammate without sharing your whole endpoint

Save a captured request​

  1. Open a debug endpoint.
  2. Select a captured request.
  3. Click Save as replay case.
  4. Give the case a name and optional notes.
  5. Optionally set a default target URL, request method, headers, or body override.

The case keeps a link to the original captured request and uses the captured method, headers, and body unless you configure overrides.

Add assertions​

Assertions run after a case replay finishes. A case can check:

AssertionDescription
Expected HTTP statusThe replay target must return a specific status code, from 100 to 599
Expected JSON response subsetThe replay target's JSON body must include the configured fields and values

If a case has no assertions, the replay still records delivery details but the assertion status is No assertions.

Replay a case​

From the case row, click Replay saved case and choose a target:

TargetUse it for
Custom URLReplay to a one-off URL such as https://staging.example.com/webhooks
Named replay targetSave a reusable target like Staging or Preview for future suite runs
CLI listenerReplay to an active hooklistener listen session

Each replay creates a forward record with the target response, duration, errors, and assertion result.

Organize suites​

Suites are named groups of cases on the same endpoint.

  1. Open the endpoint's saved cases area.
  2. Click New suite.
  3. Add cases from each case row.
  4. Click Replay all on the suite.

Suites are useful for smoke tests such as "Billing webhooks" or "GitHub issue lifecycle".

Run all endpoint cases​

Click Replay all to run every saved case on the endpoint. Hooklistener queues each replay and creates a durable suite run report with:

  • Total, queued, completed, and failed counts
  • Assertion pass/fail/error counts
  • The target used for the run
  • A list of individual forward attempts with poll URLs

Run reports remain available after the browser session closes, so API and MCP clients can start a run and fetch the report later.

API and MCP​

Replay cases are also available through: