Response Assertions & Payload Validation

An assertion is a validation rule that instructs SteadyStack on what a healthy response looks like beyond just "the web server replied."

Without assertions, a monitor reports UP whenever a server responds — even if that response is a soft 200 error page, a database connection failure splash screen, or a JSON payload with "status": "degraded". Assertions eliminate silent outages by enforcing that the response strictly satisfies your payload contracts.

When any assertion fails, SteadyStack marks the check cycle as DOWN and records the exact reason in telemetry logs.

Supported Assertion Types

You can configure five assertion types in a single expectation block. All defined assertions must pass for the check to report UP.

1. HTTP Status Codes Check

Verify that the response returns one of the acceptable HTTP status codes.

{
  "expectation": {
    "status_codes": [200, 201]
  }
}

2. Body Contains

Verify that the response body contains a specific required substring anywhere in the raw text.

{
  "expectation": {
    "body_contains": "\"status\":\"healthy\""
  }
}

3. Body Excludes

Verify that the response body does not contain forbidden substrings (e.g., error messages or maintenance banners).

{
  "expectation": {
    "body_excludes": "maintenance mode"
  }
}

4. Body Regular Expressions (Regex)

Apply a regular expression against the response body. The check passes only if the regex finds a valid match.

{
  "expectation": {
    "body_regex": "\"version\":\\s*\"2\\.[0-9]+\""
  }
}

5. JSON Path & Rich Field Assertions

Evaluate dot-notation path expressions against the parsed JSON response body.

{
  "expectation": {
    "json_path": {
      "data.status": "healthy",
      "services.database": "connected"
    }
  }
}

For richer comparison logic, use the json_assertions array:

{
  "expectation": {
    "json_assertions": [
      { "path": "$.status", "operator": "equals", "value": "ok" },
      { "path": "$.version", "operator": "contains", "value": "v2." },
      { "path": "$.error_count", "operator": "equals", "value": "0" },
      { "path": "$.maintenance", "operator": "not_equals", "value": "true" }
    ]
  }
}

Supported JSON Operators: equals (==), not_equals (!=), contains, not_contains.

6. Body Size Thresholds

Alert when the response body crosses a size threshold, measured against the exact received byte count. Useful for catching bloated responses, truncated payloads, or empty error pages served with a 200 status.

{
  "expectation": {
    "max_body_size_bytes": 1048576,
    "min_body_size_bytes": 100
  }
}

Both keys are optional and independent. The check fails with BODY_TOO_LARGE or BODY_TOO_SMALL and the alert includes the measured size. Hard platform ceiling: 5 MB regardless of thresholds.

Configuring via Terraform / OpenTofu

Declare response assertions directly in your infrastructure as code:

resource "steadystack_monitor" "api_health" {
  name     = "Production API Gateway"
  url      = "https://api.example.com/health"
  type     = "HTTP"
  interval = 30

  # Response Expectations
  expectation_json = jsonencode({
    status_codes  = [200]
    body_contains = "\"status\":\"ok\""
    body_excludes = "Fatal Error"
    json_path = {
      "status"            = "ok"
      "database.healthy"  = "true"
    }
  })
}

Configuring via CLI YAML Manifest

monitors:
  - name: User Authentication Microservice
    url: https://auth.example.com/health
    type: HTTP
    method: GET
    interval: 30
    timeout: 5
    expectation:
      status_codes: [200]
      json_assertions:
        - path: $.status
          operator: equals
          value: healthy
        - path: $.active_sessions
          operator: not_equals
          value: "0"

Common Assertion Recipes

Diagnostic Tool: Payload Regex Tester

Before deploying complex regular expressions to production monitors, test your pattern against sample response bodies using our free interactive tool at /tools/payload-regex.