Request Cases API

Request cases save captured webhook requests as repeatable replay tests. Cases can include response assertions, belong to named suites, and produce durable run reports.

Save a request as a case

POST /api/v1/endpoints/:endpoint_id/requests/:request_id/cases

curl -X POST https://app.hooklistener.com/api/v1/endpoints/ep_abc123/requests/req_def456/cases \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "case": {
      "name": "Stripe payment succeeded",
      "notes": "Regression case for checkout completion",
      "default_target_url": "https://staging.example.com/webhooks/stripe",
      "assertion_config": {
        "expected_status_code": 200,
        "expected_json_body_subset": {"received": true}
      }
    }
  }'

Case fields:

Field	Type	Description
`name`	string	Display name, up to 120 characters
`notes`	string	Optional notes, up to 2,000 characters
`default_target_url`	string	Default URL used when replaying this case
`default_method`	string	Optional method override: `GET`, `POST`, `PUT`, `PATCH`, `DELETE`, `HEAD`, `OPTIONS`, or `TRACE`
`default_request_headers`	object	Optional request header overrides
`default_request_body`	string	Optional request body override
`assertion_config.expected_status_code`	integer	Expected response status, from `100` to `599`
`assertion_config.expected_json_body_subset`	object	JSON subset expected in the replay response body
`baseline_forward_id`	string	Optional forward ID to keep as a baseline

Response: 201 Created

List endpoint cases

GET /api/v1/endpoints/:endpoint_id/cases

curl https://app.hooklistener.com/api/v1/endpoints/ep_abc123/cases \
  -H "Authorization: Bearer hklst_your_api_key"

Get, update, or delete a case

GET /api/v1/cases/:id
PUT /api/v1/cases/:id
PATCH /api/v1/cases/:id
DELETE /api/v1/cases/:id

curl -X PATCH https://app.hooklistener.com/api/v1/cases/case_abc123 \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "case": {
      "assertion_config": {
        "expected_status_code": 204
      }
    }
  }'

Replay one case

POST /api/v1/cases/:id/replay

curl -X POST https://app.hooklistener.com/api/v1/cases/case_abc123/replay \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "target_url": "https://staging.example.com/webhooks/stripe"
  }'

Replay target options:

Field	Description
`target_url`	Replay to a custom URL
`target_id`	Replay to a saved endpoint replay target
`target`	Set to `cli` to replay through an active CLI listener
`method`	Optional method override for this replay
`request_headers`	Optional request header overrides
`request_body`	Optional request body override

Response: 202 Accepted

{
  "data": {
    "forward_id": "fwd_abc123",
    "debug_request_case_id": "case_abc123",
    "target_url": "https://staging.example.com/webhooks/stripe",
    "status": "queued",
    "assertion_status": "queued",
    "poll_url": "/api/v1/forwards/fwd_abc123"
  }
}

Poll the returned forward with Request Forwarding API to inspect delivery and assertion results.

Case suites

Suites group saved cases for the same endpoint.

GET /api/v1/endpoints/:endpoint_id/case-suites
POST /api/v1/endpoints/:endpoint_id/case-suites
GET /api/v1/case-suites/:id
PUT /api/v1/case-suites/:id
PATCH /api/v1/case-suites/:id
DELETE /api/v1/case-suites/:id

curl -X POST https://app.hooklistener.com/api/v1/endpoints/ep_abc123/case-suites \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "case_suite": {
      "name": "Billing regression",
      "description": "Critical Stripe webhook cases"
    }
  }'

Add or remove cases:

POST /api/v1/case-suites/:id/cases
POST /api/v1/case-suites/:id/cases/:case_id
DELETE /api/v1/case-suites/:id/cases/:case_id

curl -X POST https://app.hooklistener.com/api/v1/case-suites/suite_abc123/cases \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"case_id": "case_def456", "position": 1}'

Run cases

Run every saved case on an endpoint, or only one suite.

POST /api/v1/endpoints/:endpoint_id/cases/run

curl -X POST https://app.hooklistener.com/api/v1/endpoints/ep_abc123/cases/run \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "case_suite_id": "suite_abc123",
    "target_url": "https://staging.example.com/webhooks",
    "target_name": "Staging",
    "wait": true,
    "timeout_ms": 30000
  }'

Run fields:

Field	Description
`case_suite_id`	Optional suite ID. Omit to run all endpoint cases
`target_url`	Destination URL for each case
`target_id`	Saved endpoint replay target ID
`target`	Set to `cli` to use an active CLI listener
`target_name`	Optional name to save for a custom `target_url`
`wait`	When true, wait for queued forwards and aggregate results
`timeout_ms`	Wait timeout. Defaults to `30000`, capped at `120000`
`interval_ms`	Polling interval. Defaults to `250`

Response: 202 Accepted for queued runs, or 200 OK when wait=true and all queued forwards finish before timeout.

{
  "data": {
    "case_suite_run_id": "run_abc123",
    "case_suite_run_url": "/api/v1/case-runs/run_abc123",
    "endpoint_id": "ep_abc123",
    "queued_count": 3,
    "failed_count": 0,
    "result_status": "pending",
    "forwards": [
      {
        "id": "fwd_abc123",
        "poll_url": "/api/v1/forwards/fwd_abc123"
      }
    ]
  }
}

Case run reports

GET /api/v1/endpoints/:endpoint_id/case-runs
GET /api/v1/case-runs/:id
POST /api/v1/case-runs/:id/wait

curl https://app.hooklistener.com/api/v1/case-runs/run_abc123 \
  -H "Authorization: Bearer hklst_your_api_key"

Case run reports include aggregate delivery counts, assertion counts, target metadata, failures, and the forward attempts created by the run.

Saved cases use /c/ share URLs.

POST /api/v1/cases/:case_id/share
GET /api/v1/cases/:case_id/shares
DELETE /api/v1/shared/c/:token
GET /api/v1/shared/c/:token
POST /api/v1/shared/c/:token/authenticate

curl -X POST https://app.hooklistener.com/api/v1/cases/case_abc123/share \
  -H "Authorization: Bearer hklst_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "share": {
      "expires_in_hours": 24,
      "password": "optional-password",
      "include_replay_history": true
    }
  }'

Save a request as a case​

List endpoint cases​

Get, update, or delete a case​

Replay one case​

Case suites​

Run cases​

Case run reports​

Share a saved case​