Conditional Node

The Conditional node provides multi-branch routing logic for your webhook pipeline. Define named branches with filters, and events are routed to the first matching branch — with an else path for events that match no branch.

Overview

The Conditional node evaluates named branches in order against the incoming event payload. Each branch has its own set of filters and output targets. The first branch whose filters match wins — the event is routed to that branch's output nodes. If no branch matches, the event falls through to the else path.

ℹBranches are evaluated in order — first match wins. If no branch matches, the event is routed through the else path (elseWebhookIds / elseTransformIds).

Configuration

Field	Type	Default	Description
name	string	—	Friendly label for the conditional
branches	Branch[]	—	Array of named branches evaluated in order (first match wins)
elseWebhookIds	string[]	[]	Webhook IDs for the else path (when no branch matches)
elseTransformIds	string[]	[]	Transform IDs for the else path
inputNodes	{ nodeType, nodeId }[]	[]	Upstream nodes that feed this one. nodeType is the node kind (webhook, scheduledWorkflow, filter, …)
isActive	boolean	true	Whether the conditional is enabled

Branch Object

Field	Type	Description
name	string	Human-readable label for this branch (e.g. "High value")
filters	PayloadFilter[]	Array of filter conditions to evaluate against the payload
filterMode	'and' \| 'or'	How to combine filters — all must match (and) or any (or)
outputNodes	string[]	Node IDs to route to when this branch matches
outputWebhookIds	string[]	Webhook IDs to route to when this branch matches
outputTransformIds	string[]	Transform IDs to route to when this branch matches

Create a Conditional

Define branches with filters and output targets. The first branch whose filters match wins. Use elseWebhookIds and elseTransformIds for events that match no branch.

bashCreate Conditional with branches

curl -X POST /api/conditionals \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Payment Amount Router",
    "branches": [
      {
        "name": "High value",
        "filters": [
          { "field": "data.object.amount", "operator": "gt", "value": "5000" }
        ],
        "filterMode": "and",
        "outputNodes": ["delay_6655aaa", "discord_6655bbb"],
        "outputWebhookIds": [],
        "outputTransformIds": []
      },
      {
        "name": "Standard",
        "filters": [
          { "field": "data.object.amount", "operator": "lte", "value": "5000" }
        ],
        "filterMode": "and",
        "outputNodes": [],
        "outputWebhookIds": ["ep_standard_processing"],
        "outputTransformIds": []
      }
    ],
    "elseWebhookIds": ["ep_fallback"],
    "elseTransformIds": [],
    "inputNodes": [{ "nodeType": "webhook", "nodeId": "6654a1b2c3d4e5f6a7b8c9d0" }],
    "isActive": true
  }'

Response

json201 Created

{
  "_id": "6655b8c9d0e1f2a3b4c5d6e7",
  "name": "Payment Amount Router",
  "branches": [
    {
      "name": "High value",
      "filters": [
        { "field": "data.object.amount", "operator": "gt", "value": "5000" }
      ],
      "filterMode": "and",
      "outputNodes": ["delay_6655aaa", "discord_6655bbb"],
      "outputWebhookIds": [],
      "outputTransformIds": []
    },
    {
      "name": "Standard",
      "filters": [
        { "field": "data.object.amount", "operator": "lte", "value": "5000" }
      ],
      "filterMode": "and",
      "outputNodes": [],
      "outputWebhookIds": ["ep_standard_processing"],
      "outputTransformIds": []
    }
  ],
  "elseWebhookIds": ["ep_fallback"],
  "elseTransformIds": [],
  "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 Conditional

bashUpdate Conditional

curl -X PATCH /api/conditionals/6655b8c9d0e1f2a3b4c5d6e7 \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "branches": [
      {
        "name": "VIP",
        "filters": [
          { "field": "data.object.amount", "operator": "gt", "value": "50000" }
        ],
        "filterMode": "and",
        "outputNodes": ["delay_6655aaa", "discord_6655bbb"],
        "outputWebhookIds": [],
        "outputTransformIds": []
      },
      {
        "name": "Standard",
        "filters": [
          { "field": "data.object.amount", "operator": "lte", "value": "50000" }
        ],
        "filterMode": "and",
        "outputNodes": [],
        "outputWebhookIds": ["ep_standard_processing"],
        "outputTransformIds": []
      }
    ],
    "elseWebhookIds": ["ep_fallback"]
  }'

Canvas Integration

On the canvas, the Conditional node renders with one outgoing edge per branch (labeled with the branch name) and an additional dashed edge labeled "else" for the fallback path. The canvas type is conditional with blue styling.

jsonCanvas representation

{
  "id": "conditional-6655b8c9d0e1f2a3b4c5d6e7",
  "type": "conditional",
  "position": { "x": 400, "y": 200 },
  "data": {
    "label": "Payment Amount Router",
    "conditionalId": "6655b8c9d0e1f2a3b4c5d6e7",
    "branchCount": 2,
    "hasElse": true,
    "isActive": true
  }
}

Payload Examples

Branch 1 matches — high value

jsonRouted to 'High value' branch

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "amount": 25000,
      "currency": "usd",
      "customer": "cus_vip123"
    }
  }
}
// amount (25000) > 5000 -> matches "High value" branch
// -> routed to delay_6655aaa -> discord_6655bbb

Branch 2 matches — standard

jsonRouted to 'Standard' branch

{
  "type": "payment_intent.succeeded",
  "data": {
    "object": {
      "amount": 3500,
      "currency": "usd",
      "customer": "cus_regular456"
    }
  }
}
// amount (3500) <= 5000 -> matches "Standard" branch
// -> routed to ep_standard_processing

No branch matches — else path

jsonRouted to else path

{
  "type": "payment_intent.failed",
  "data": {
    "object": {
      "error": "card_declined"
    }
  }
}
// no "amount" field -> no branch matches
// -> routed to elseWebhookIds (ep_fallback)

Use Cases

Amount thresholds — Route high-value transactions to a VIP processing pipeline and standard ones to the regular flow.
Feature gating — Check for a feature flag field in the payload and route to different processing versions.
Error handling — Check if the payload contains an error field; route errors to an error handler and successes to the main pipeline.
A/B testing — Split events based on a user segment field to test different processing logic.
Region-based routing — Route events to US or EU processing webhooks based on a region field.

API Reference

The Conditional node has its own API endpoints:

Method	Webhook	Description
GET	/api/conditionals	List all conditionals
POST	/api/conditionals	Create a new conditional
GET	/api/conditionals/:id	Get a specific conditional
PATCH	/api/conditionals/:id	Update a conditional
DELETE	/api/conditionals/:id	Delete a conditional

✦Use filterMode: "and" when all conditions in a branch must be true, or "or" when any single condition is enough to match.

ℹBranches support outputNodes for connecting to any node type (delays, Discord actions, etc.) in addition to outputWebhookIds and outputTransformIds for direct webhook/transform routing.