Triggers

Start workflows with various trigger types

Triggers determine when and how your workflow starts. Every workflow needs exactly one trigger.

Trigger Types

Manual Trigger

Start workflows on demand with a button click.

Use Cases:

  • Testing and debugging
  • One-time tasks
  • Admin operations

Configuration:

json
{
  "type": "manual",
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": { "type": "string" },
      "action": { "type": "string" }
    },
    "required": ["customer_id"]
  }
}

Webhook Trigger

Start workflows via HTTP request from external systems.

Use Cases:

  • Third-party integrations
  • Event-driven automation
  • API endpoints

Configuration:

json
{
  "type": "webhook",
  "method": "POST",
  "path": "/custom-path",
  "authentication": {
    "type": "bearer",
    "token": "your-secret-token"
  }
}

Webhook URL:

https://hooks.arcanflows.io/v1/workflows/{workflow_id}/webhook

Example Request:

bash
curl -X POST https://hooks.arcanflows.io/v1/workflows/wf_123/webhook \
  -H "Authorization: Bearer your-secret-token" \
  -H "Content-Type: application/json" \
  -d '{"event": "order.created", "data": {"id": "ord_456"}}'

Schedule Trigger

Run workflows on a recurring schedule using cron expressions.

Use Cases:

  • Daily reports
  • Periodic cleanup
  • Scheduled notifications

Configuration:

json
{
  "type": "schedule",
  "cron": "0 9 * * 1-5",
  "timezone": "America/New_York"
}

Common Cron Patterns:

PatternDescription
0 * * * *Every hour
0 9 * * *Daily at 9 AM
0 9 * * 1-5Weekdays at 9 AM
0 0 * * 0Weekly on Sunday
0 0 1 * *Monthly on the 1st

Cron Format:

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

Form Trigger

Start workflows when a form is submitted.

Use Cases:

  • Lead capture processing
  • Support ticket creation
  • User onboarding

Configuration:

json
{
  "type": "form",
  "form_id": "form_abc123",
  "include_metadata": true
}

Accessing Form Data:

javascript
// Form fields
{{ input.name }}
{{ input.email }}
{{ input.message }}

// Submission metadata
{{ input._metadata.submitted_at }}
{{ input._metadata.ip_address }}
{{ input._metadata.user_agent }}

Event Trigger

Start workflows based on system events.

Use Cases:

  • User actions
  • Data changes
  • System notifications

Available Events:

EventDescription
agent.conversation.startedNew agent chat started
agent.conversation.endedAgent chat completed
form.submittedAny form submitted
workflow.completedAnother workflow finished
workflow.failedAnother workflow failed

Configuration:

json
{
  "type": "event",
  "event_name": "agent.conversation.ended",
  "filters": {
    "agent_id": "agent_123"
  }
}

Chat Trigger

Start workflows from agent conversations.

Use Cases:

  • Agent tool calls
  • Conversation handoffs
  • Escalation flows

Configuration:

json
{
  "type": "chat",
  "agent_id": "agent_123",
  "trigger_phrase": "create_ticket"
}

Trigger Input Data

All triggers provide input data to the workflow:

Webhook Input

javascript
{
  "headers": {
    "content-type": "application/json",
    "x-custom-header": "value"
  },
  "body": {
    // Request body
  },
  "query": {
    // URL query parameters
  },
  "method": "POST",
  "path": "/webhook"
}

Schedule Input

javascript
{
  "scheduled_time": "2025-01-15T09:00:00Z",
  "execution_id": "exec_123",
  "schedule": {
    "cron": "0 9 * * 1-5",
    "timezone": "America/New_York"
  }
}

Form Input

javascript
{
  "field_1": "value_1",
  "field_2": "value_2",
  "_metadata": {
    "form_id": "form_123",
    "submission_id": "sub_456",
    "submitted_at": "2025-01-15T10:30:00Z"
  }
}

Authentication Options

No Authentication

Open webhook (use with caution):

json
{
  "authentication": {
    "type": "none"
  }
}

Bearer Token

Simple token authentication:

json
{
  "authentication": {
    "type": "bearer",
    "token": "your-secret-token"
  }
}

API Key

Header-based API key:

json
{
  "authentication": {
    "type": "api_key",
    "header": "X-API-Key",
    "key": "your-api-key"
  }
}

HMAC Signature

Verify webhook signatures:

json
{
  "authentication": {
    "type": "hmac",
    "secret": "your-secret",
    "header": "X-Signature",
    "algorithm": "sha256"
  }
}

Input Validation

Define expected input schema:

json
{
  "input_schema": {
    "type": "object",
    "properties": {
      "customer_id": {
        "type": "string",
        "pattern": "^cust_[a-z0-9]+$"
      },
      "amount": {
        "type": "number",
        "minimum": 0
      },
      "email": {
        "type": "string",
        "format": "email"
      }
    },
    "required": ["customer_id", "amount"]
  }
}

Invalid input returns a 400 error with validation details.

Best Practices

Security

  1. Always use authentication for webhooks
  2. Validate input to prevent malformed data
  3. Use HTTPS for all webhook URLs
  4. Rotate tokens periodically

Reliability

  1. Handle duplicates - webhooks may retry
  2. Idempotent operations - same input, same result
  3. Timeout handling - respond quickly to webhooks

Monitoring

  1. Log trigger events for debugging
  2. Set up alerts for failures
  3. Monitor trigger rates for anomalies

Next Steps