Circuitry Logo
Circuitry
Open Circuitry

Start Node

The Start node is the entry point for every workflow. It provides the initial data and configuration that flows through your automation.

Overview

Every workflow must have exactly one Start node. It defines:

  • Initial input data for the workflow
  • Trigger configuration (manual, scheduled, or webhook)
  • Test data for development and debugging

Configuration

Input Data

The Start node accepts JSON data that becomes available to all downstream nodes:

{
  "customer": {
    "id": "12345",
    "email": "customer@example.com",
    "name": "John Doe"
  },
  "order": {
    "items": ["product-1", "product-2"],
    "total": 99.99
  }
}

Trigger Types

Manual Trigger

Default mode - workflow runs when you click "Run" or trigger via API.

Scheduled Trigger

Configure workflows to run automatically:

  • Cron expressions: 0 9 * * 1 (Every Monday at 9 AM)
  • Intervals: Every 5 minutes, hourly, daily
  • Time zones: Specify timezone for scheduled runs

Webhook Trigger

Start workflows from external events:

  • Unique webhook URL generated for each workflow
  • Supports GET, POST, PUT, DELETE methods
  • Automatic JSON parsing of request body
  • Headers and query parameters accessible

Using the Start Node

Basic Setup

  1. Add Start node to your canvas (usually pre-added)
  2. Click to configure in the right panel
  3. Enter test data in JSON format
  4. Connect to your first processing node

Accessing Start Data

Downstream nodes access start data through the input variable:

In Code nodes:

// The entire start payload is the `input` object.
// Read specific fields and return what the next node needs:
const customerEmail = input.customer.email;
const orderTotal = input.order.total;

return { customerEmail, orderTotal };

In Agent nodes:

Process order for {{input.customer.name}} 
Total amount: {{input.order.total}}

Examples

E-commerce Order Processing

{
  "orderId": "ORD-2024-001",
  "customer": {
    "id": "CUST-123",
    "email": "buyer@example.com",
    "tier": "premium"
  },
  "items": [
    {
      "sku": "WIDGET-A",
      "quantity": 2,
      "price": 29.99
    }
  ],
  "shipping": {
    "method": "express",
    "address": "123 Main St, City, ST 12345"
  }
}

Data Analysis Request

{
  "dataset": "sales_2024",
  "metrics": ["revenue", "units", "customers"],
  "groupBy": "region",
  "dateRange": {
    "start": "2024-01-01",
    "end": "2024-03-31"
  },
  "format": "summary"
}

API Integration Setup

{
  "source": {
    "api": "https://api.source.com/data",
    "headers": {
      "Accept": "application/json"
    }
  },
  "transformation": {
    "filter": "active",
    "limit": 100
  },
  "destination": {
    "webhook": "https://destination.com/receive"
  }
}

Best Practices

1. Use Descriptive Keys

// ❌ Bad
{
  "d": "2024-01-01",
  "v": 100
}

// ✅ Good
{
  "orderDate": "2024-01-01",
  "orderValue": 100
}

2. Validate Required Fields

Always include fields that downstream nodes expect:

{
  "required": {
    "userId": "USER-123",
    "action": "process"
  },
  "optional": {
    "priority": "high"
  }
}

3. Use Test Data

During development, use realistic test data:

{
  "testMode": true,
  "testData": {
    "scenario": "happy-path",
    "expectedResult": "success"
  },
  "actualData": {
    // Your real data structure
  }
}

Webhook Configuration

Setting Up Webhooks

  1. Change trigger type to "Webhook" in Start node
  2. Copy webhook URL from the configuration panel
  3. Configure security (optional):
    • API Key authentication
    • IP allowlisting
    • HMAC signatures

Webhook URL Format

https://your-domain.com/api/webhook/workflow/{workflowId}

Accessing Webhook Data

When triggered by webhook, the Start node provides:

{
  "body": { /* JSON request body */ },
  "headers": { /* HTTP headers */ },
  "query": { /* Query parameters */ },
  "method": "POST",
  "path": "/api/webhook/workflow/abc123"
}

Environment Variables

Reference environment variables in Start node data:

{
  "apiEndpoint": "env:API_BASE_URL",
  "debugMode": "env:DEBUG_ENABLED",
  "configuration": {
    "timeout": 30000,
    "retries": 3
  }
}

Scheduled Execution

Cron Expressions

Common patterns:

  • */5 * * * * - Every 5 minutes
  • 0 * * * * - Every hour
  • 0 0 * * * - Daily at midnight
  • 0 9 * * 1-5 - Weekdays at 9 AM
  • 0 0 1 * * - First day of each month

Time Zone Handling

Specify timezone for scheduled runs:

{
  "schedule": {
    "cron": "0 9 * * *",
    "timezone": "America/New_York"
  }
}

Troubleshooting

"No Start node found"

  • Ensure exactly one Start node exists
  • Check node connections are properly linked

"Invalid JSON in Start node"

  • Validate JSON syntax (check for trailing commas)
  • Use the JSON validator in the editor
  • Ensure all strings are quoted

"Webhook not triggering"

  • Verify webhook URL is correct
  • Check authentication settings
  • Review webhook logs for errors
  • Ensure workflow is published/active

Tips

  1. Keep it simple: Start with minimal data, add complexity gradually
  2. Use comments: Document your data structure for team members
  3. Version control: Track changes to Start node configuration
  4. Test thoroughly: Use different input scenarios
  5. Monitor performance: Large payloads may slow execution

Related Topics