Webhooks

Workflows with a Webhook trigger can be executed by external systems via an HTTP POST request. This is how you integrate Orchestrator into your applications, CI/CD pipelines, or third-party services.

Webhook URL

Every workflow has a unique webhook endpoint:

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

Replace {workflowId} with your workflow's ID (visible in the browser URL when editing).

Authentication

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

Authorization: Bearer wfb_your_key_here

The key must:

• Start with wfb_ prefix
• Be valid (not deleted)
• Belong to the same user who owns the workflow

See API Keys to create and manage Orchestrator keys.

Request Format

curl -X POST "https://orchestrator.skytells.ai/api/workflows/{workflowId}/webhook" \
  -H "Authorization: Bearer wfb_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "event": "order.created",
    "orderId": "ord_123",
    "customerEmail": "[email protected]"
  }'

Request body: Any valid JSON. The entire body becomes the trigger node's output, accessible to downstream actions via template variables.

Response

Success (200)

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

The workflow starts executing asynchronously. Use the executionId to check progress via the execution status API.

Error Responses

CORS

The webhook endpoint supports CORS preflight requests:

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

Response headers include:

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

This means you can call the webhook directly from browser-based applications.

Webhook Schema

When configuring a Webhook trigger, you can optionally define a schema describing the expected request body. This serves as documentation for consumers of your webhook — it doesn't enforce validation on incoming requests.

Use the Schema Builder in the trigger config panel to define fields, types, and descriptions.

Mock Request for Testing

Set a Mock Request JSON payload in the trigger config. When you run the workflow manually from the editor, this payload is used as the trigger input instead of requiring an actual HTTP request. This lets you test webhook-triggered workflows without setting up external callers.

Integration Patterns

From your application

Call the webhook when an event occurs in your app:

await fetch(`https://orchestrator.skytells.ai/api/workflows/${workflowId}/webhook`, {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.ORCHESTRATOR_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    event: 'user.signup',
    userId: user.id,
    email: user.email,
  }),
});

From a third-party service

Many services support webhook notifications (Stripe, GitHub, etc.). Configure them to POST to your Orchestrator webhook URL with the API key in the header.

Polling for completion

After triggering, poll the execution status:

# Check execution status
curl "https://orchestrator.skytells.ai/api/workflows/executions/{executionId}/status" \
  -H "Cookie: session=..."

# Get detailed step logs
curl "https://orchestrator.skytells.ai/api/workflows/executions/{executionId}/logs" \
  -H "Cookie: session=..."

Best Practices

• Use separate Orchestrator API keys per environment (dev/staging/prod)
• Include a request ID in your payload for traceability
• Store the returned executionId in your system for debugging
• Set up the webhook schema to document your API contract
• Test with the mock request feature before going live

Next Steps