Schema Validator Node

The Schema Validator checks the event payload against a set of field definitions you build on screen. A payload that fails stops the pipeline right there — nothing else in the flow is dispatched — and on a webhook in Sync response mode it is also what answers the caller.

Overview

Schema Validators act as structural gatekeepers in your pipeline. They inspect the incoming event payload against a set of field definitions, checking that required fields are present, values match expected types, and constraints (min, max, pattern, etc.) are satisfied. When a payload fails validation the pipeline stops there: neither the validator's own outputs nor any other node in the flow is dispatched. There is no “invalid” branch — put a Conditional in front of the validator if you need one.

In strictMode, any fields present in the payload that are NOT defined in the schema will also cause validation to fail. This prevents unexpected data from passing through. On the canvas, Schema Validator nodes appear in cyan (#06b6d4) with an ID prefix of sv-.

Configuration

SchemaField object

Constraints

Create a Schema Validator

curl -X POST /api/schema-validators \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": "<your-workspace-id>",
    "name": "Payment Event Schema",
    "strictMode": false,
    "fields": [
      {
        "path": "type",
        "type": "string",
        "required": true,
        "constraints": {
          "enum": ["payment_intent.succeeded", "payment_intent.payment_failed", "charge.succeeded"]
        }
      },
      {
        "path": "data.object.amount",
        "type": "number",
        "required": true,
        "constraints": {
          "min": 0,
          "max": 99999999
        }
      },
      {
        "path": "data.object.currency",
        "type": "string",
        "required": true,
        "constraints": {
          "minLength": 3,
          "maxLength": 3,
          "pattern": "^[a-z]{3}$"
        }
      },
      {
        "path": "data.object.customer",
        "type": "string",
        "required": false
      },
      {
        "path": "data.object.metadata",
        "type": "object",
        "required": false
      }
    ],
    "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }],
    "isActive": true
  }'

Response

{
  "_id": "6655a7b8c9d0e1f2a3b4c5d6",
  "name": "Payment Event Schema",
  "strictMode": false,
  "fields": [
    {
      "path": "type",
      "type": "string",
      "required": true,
      "constraints": {
        "enum": ["payment_intent.succeeded", "payment_intent.payment_failed", "charge.succeeded"]
      }
    },
    {
      "path": "data.object.amount",
      "type": "number",
      "required": true,
      "constraints": { "min": 0, "max": 99999999 }
    },
    {
      "path": "data.object.currency",
      "type": "string",
      "required": true,
      "constraints": { "minLength": 3, "maxLength": 3, "pattern": "^[a-z]{3}$" }
    },
    {
      "path": "data.object.customer",
      "type": "string",
      "required": false
    },
    {
      "path": "data.object.metadata",
      "type": "object",
      "required": false
    }
  ],
  "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }],
  "isActive": true,
  "ownerId": "org_abc123",
  "createdAt": "2025-05-01T12:00:00.000Z",
  "updatedAt": "2025-05-01T12:00:00.000Z"
}

Update a Schema Validator

curl -X PATCH /api/schema-validators/6655a7b8c9d0e1f2a3b4c5d6 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "strictMode": true,
    "fields": [
      {
        "path": "type",
        "type": "string",
        "required": true,
        "constraints": {
          "enum": ["payment_intent.succeeded"]
        }
      },
      {
        "path": "data.object.amount",
        "type": "number",
        "required": true,
        "constraints": { "min": 1 }
      },
      {
        "path": "data.object.currency",
        "type": "string",
        "required": true
      }
    ]
  }'

Canvas Integration

Schema Validator nodes use the ID prefix sv- on the canvas and are rendered in cyan (#06b6d4). They connect to webhooks and run early in the onEventCreated phase — before the rest of the pipeline, and after the primary delivery to the webhook's target URL has already been queued.

{
  "id": "sv-6655a7b8c9d0e1f2a3b4c5d6",
  "type": "schema-validator",
  "position": { "x": 250, "y": 200 },
  "data": {
    "label": "Payment Event Schema",
    "schemaValidatorId": "6655a7b8c9d0e1f2a3b4c5d6",
    "strictMode": false,
    "fieldCount": 5,
    "isActive": true
  }
}

Payload Examples

Valid payload — passes validation

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "amount": 5000,
      "currency": "usd",
      "customer": "cus_abc123"
    }
  }
}
// Result: PASSES — all required fields present, types match, constraints satisfied

Invalid payload — blocked

{
  "type": "invoice.finalized",
  "data": {
    "object": {
      "amount": -500,
      "currency": "US"
    }
  }
}
// Validation errors, in the wording the validator actually produces:
// - "type": must be one of: payment_intent.succeeded, charge.refunded
// - "data.object.amount": must be >= 0
// - "data.object.currency": must be at least 3 characters

What a rejection leaves behind

A rejection is the node doing its job, not a breakdown, so it is recorded as a warning rather than an error — an event stopped in its tracks is not just another line in the noise either. The log entry carries the errors in its metadata, and the node's lastInvalidPayload keeps the body that failed, next to the lastValidPayload of the last one that passed.

{
  "level": "warn",
  "source": "schema_validator",
  "message": "Schema \"Payment Event Schema\" INVALID — 2 error(s)",
  "statusCode": 422,
  "nodeName": "Payment Event Schema",
  "success": false,
  "metadata": {
    "valid": false,
    "strictMode": false,
    "fieldCount": 5,
    "errors": [
      { "path": "data.object.amount", "message": "must be >= 0" },
      { "path": "data.object.currency", "message": "must be at least 3 characters" }
    ]
  }
}

Answering a Sync webhook

The Schema Validator answers a webhook in Sync response mode — the only other node that can is the AI Node, and Sync cannot be switched on for a flow that carries neither. It answers at its own step, before dispatching anything downstream, so the caller's connection is held for one validation rather than for the length of the workflow.

payload fails  →  this validator's error response (422 by default)
payload passes →  held until the last validator on the path has passed,
                  then 200  { "accepted": true, "eventId": "…" }
                  and the rest of the flow keeps running behind it

In None response mode nothing changes: the validator blocks the pipeline exactly as described above and nobody is waiting on an answer.

Reply only mode

A Schema Validator has two modes. Validate — mode: "validate", the default — is everything described above. Reply only — mode: "reply" — validates nothing: when the run reaches the node, whoever is holding the connection open (the caller of a webhook in Sync response mode) gets the response you configured on it, and the connection closes. The payload goes through untouched and everything downstream is dispatched as usual.

It is meant for the end of an error branch. A Conditional or a Filter decides the event is one you will not process — an order that was already handled, a customer you do not know, an API version you no longer accept — and the branch it routes to ends in a Reply-only validator that tells the caller so, with a status and a body of your own. A validating Schema Validator can only say “the payload does not match the schema”; a Reply-only one says whatever you decide, on whichever branch you put it.

Webhook, Sync mode
  └── Schema Validator (Validate)
        │   fails  → 422, pipeline stops
        │   passes → noted, connection still open
        └── Conditional   payload.status == "processed"
              ├── true → Schema Validator (Reply only)
              │            409 { "error": "Order … was already processed" } — final,
              │            and whatever hangs below it still runs
              └── else → HTTP Action → …
                           nothing else answers: the Validate step's 200, as usual

What you configure

Two fields, sent on POST /api/schema-validators and PATCH /api/schema-validators/:id, and edited in the validator's panel once the mode is switched. Both parts of reply are optional.

In the panel you do not type that JSON: the body box takes lines. One key: value per line; indent under a bare key: to nest — key: value lines make an object, - value lines make a list, and - key: value starts an object inside a list. Numbers and true/false are typed; wrap a value in quotes to keep it as text. Pasting JSON works too. The same box is used for the custom input under Run Test → Advanced.

accepted: true
order:
  id: {{payload.orderId}}
  tags:
    - checked
    - {{payload.source}}
items:
  - sku: A1
    qty: 2

{
  "accepted": true,
  "order": { "id": "ord_1042", "tags": ["checked", "stripe"] },
  "items": [{ "sku": "A1", "qty": 2 }]
}

What the caller receives is the status, the rendered body with content-type: application/json; charset=utf-8, and the X-HostWebhook-Event-Id header that every sync response carries — you do not need to put the event id in the body yourself.

Final, like a rejection — but nothing stops

A pass from a validating Schema Validator is provisional: the connection stays open in case a later validator on the path says no. A Reply-only validator is that later word. Its reply goes out the moment the run reaches it and the provisional pass is discarded — the caller never sees the 200 the earlier validator would have given. Unlike a rejection, though, it does not stop the pipeline: the payload is handed on and the nodes after it run behind the answer, just as they do behind a pass.

Example

Switch an existing validator to Reply only and give it a 409 with a message built from the payload:

curl -X PATCH /api/schema-validators/6655a7b8c9d0e1f2a3b4c5d6 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "reply",
    "reply": {
      "status": 409,
      "body": { "error": "Order {{payload.orderId}} was already processed" }
    }
  }'

A caller whose event, { "orderId": "ord_8841", … }, is routed to that validator gets:

HTTP/1.1 409 Conflict
content-type: application/json; charset=utf-8
X-HostWebhook-Event-Id: 6f3a91c2b45d8e0197ac2d64

{
  "error": "Order ord_8841 was already processed"
}

Leave reply out, or send it as null, and the same validator answers 200 with { "accepted": true, "eventId": "…" } — the plain acknowledgement, given from wherever on the canvas you put the node.

Use Cases

• Contract enforcement — Ensure incoming webhooks always match a defined schema before any processing occurs.
• Data quality gates — Block events with missing or malformed fields from polluting downstream databases.
• API versioning — Validate that payloads match a specific API version's expected structure using enum constraints on version fields.
• Strict mode for security — Enable strictMode to reject payloads with unexpected fields, preventing injection of unwanted data.
• Custom error answers — End an error branch with a validator in Reply only mode to answer a Sync caller with a status and body of your own — a 409 for an order already processed, a 410 for a retired API version.
• Debugging — Attach a schema validator to catch malformed events early and see detailed validation error reports in the dashboard.

API Reference