Contract Testing

Contract Testing validates recent events against connected schema validators to detect payload drift — giving you a health score that shows how well your incoming data matches your expected schemas.

Overview

When you connect Schema Validator nodes to a webhook on the canvas, they define the expected payload structure. Contract Testing retroactively checks recent events against those validators and produces a contract health score from 0 to 100.

A score of 100 means every recent event matches every connected validator. A declining score signals schema drift — the upstream service may have changed its payload format without notice.

ℹContract Testing is a read-only analysis. It does not block or modify events. Use Schema Validators in the pipeline to actively block invalid payloads at ingress time.

API

GET /api/events/:webhookId/contract-health?limit=100

Query parameters

Parameter	Type	Default	Description
limit	number	100	Number of recent events to check (max 500)

Response

jsonResponse

{
  "score": 87,
  "totalChecked": 100,
  "passed": 87,
  "failed": 13,
  "validators": [
    {
      "id": "664a1f2e8b1c4a001f2d0010",
      "name": "Payment Schema v2",
      "passRate": 94,
      "recentFailures": [
        {
          "eventId": "664a1f2e8b1c4a001f2d0050",
          "timestamp": "2025-05-19T14:30:00.000Z",
          "errors": [
            {
              "path": "data.object.currency",
              "expected": "string",
              "received": "null",
              "constraint": "required"
            }
          ]
        },
        {
          "eventId": "664a1f2e8b1c4a001f2d0051",
          "timestamp": "2025-05-19T14:28:00.000Z",
          "errors": [
            {
              "path": "data.object.metadata.orderId",
              "expected": "string",
              "received": "undefined",
              "constraint": "required"
            }
          ]
        }
      ]
    },
    {
      "id": "664a1f2e8b1c4a001f2d0011",
      "name": "Webhook Envelope",
      "passRate": 100,
      "recentFailures": []
    }
  ]
}

Interpreting the score

Score range	Status	Action
95 – 100	Healthy	No action needed. Payloads conform to the schema.
80 – 94	Degraded	Investigate recent failures. The upstream may have introduced optional fields or format changes.
50 – 79	Drifting	Significant schema mismatch. Update validators or coordinate with the webhook provider.
0 – 49	Broken	Most events fail validation. The schema contract is likely outdated or the provider changed their API version.

Understanding failures

Each failure entry in the recentFailures array includes:

eventId: The event that failed validation, clickable in the dashboard.
timestamp: When the event was received.
errors: Array of validation errors, each with the field path, expected type, received value, and which constraint was violated.

✦Use the recentFailures data to update your Schema Validator rules. Common drift patterns include: new optional fields, type changes (string to number), and removed required fields.

Best practices

Run contract health checks after upstream provider version upgrades.
Monitor the contract score regularly.
Start with permissive schemas and tighten constraints as you learn the real payload shapes.
Use Time Travel to test updated schemas against historical events before deploying.