Triggers & Webhooks

What you'll be able to do after this module

• Choose the right trigger type for your use case
• Set up a Webhook trigger with schema validation and mock requests
• Create Orchestrator API keys and authenticate webhook calls
• Call a workflow from cURL, JavaScript, and Python
• Configure a Schedule trigger with cron expressions

The Three Trigger Types

Every workflow starts with exactly one trigger. The trigger type determines how the workflow fires.

To change the trigger type, click the trigger node → select a new type from the dropdown in the config panel.

Manual Trigger

Manual is the default. Click Run in the toolbar and the workflow executes immediately.

Best used for:

• Building and testing workflows during development
• One-off tasks (e.g., "run this report now")
• QA testing before switching to Webhook

Webhook Trigger

A Webhook trigger gives your workflow a public HTTP endpoint that external systems can call.

Webhook URL format

POST https://orchestrator.skytells.ai/api/workflows/{workflowId}/webhook

The workflowId is visible in your browser's address bar when editing the workflow.

Authentication

Webhook calls require an Orchestrator API key in the Authorization header:

Authorization: Bearer wfb_aB3cD4eF5gH6iJ7kL8mN9oP0q

Creating an API Key

Calling the Webhook

curl -X POST \
  https://orchestrator.skytells.ai/api/workflows/YOUR_WORKFLOW_ID/webhook \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer wfb_YOUR_API_KEY" \
  -d '{
    "customer_id": "cust_123",
    "action": "onboard"
  }'

Response

{
  "executionId": "exec_abc123",
  "status": "running"
}

Webhook execution is asynchronous. The response returns immediately with a running status. Poll the execution status endpoint to track progress:

GET /api/workflows/executions/{executionId}/status

Error Codes

Webhook Schema (Optional)

You can define an expected payload schema in the trigger config using the Schema Builder. This is for documentation purposes — it helps you and your team understand the expected structure, and you can use it with the mock request feature.

Mock Requests

For testing without an actual HTTP call:

1. Enter test JSON in the Mock Request field on the Webhook trigger
2. Click Run — the workflow executes with the mock payload as trigger output
3. Inspect results in the Runs panel

This lets you iterate on webhook workflows without needing an external caller.

CORS

The webhook endpoint returns the following CORS headers, enabling direct calls from browser-based applications:

Access-Control-Allow-Origin: *
Access-Control-Allow-Methods: POST, OPTIONS
Access-Control-Allow-Headers: Content-Type, Authorization

Schedule Trigger

A Schedule trigger fires on a cron-based timer.

Configuration

Cron syntax reference

┌─────── minute (0-59)
│ ┌───── hour (0-23)
│ │ ┌─── day of month (1-31)
│ │ │ ┌─ month (1-12)
│ │ │ │ ┌ day of week (0-6, 0=Sunday)
│ │ │ │ │
* * * * *

Choosing a Trigger Type

What you now understand

Up next: API & Automation — use the REST API, export code, and generate workflows with AI.