Triggers

Trigger Types

Webhook

HTTP endpoints that start workflows when called

Schedule

Time-based triggers using cron expressions

Event

React to system or custom events

Message

Process messages from queues or streams

Configuration

Each trigger type has its own configuration options. Here are examples for each type:

trigger:
  type: webhook
  config:
    url: /workflows/process-data
    method: POST
  schema:
    type: object
    properties:
      data:
        type: object
        description: The data to process
      metadata:
        type: object
        description: Additional context
    required: [data]

trigger:
  type: schedule
  config:
    cron: "0 0 * * *"  # Daily at midnight
    timezone: UTC
  schema:
    type: object
    properties:
      timestamp:
        type: string
        format: date-time

trigger:
  type: event
  config:
    event: document.created
    source: document-service
  schema:
    type: object
    properties:
      documentId:
        type: string
      version:
        type: string
    required: [documentId]

trigger:
  type: message
  config:
    queue: data-processing
    batch_size: 10
    visibility_timeout: 300
  schema:
    type: object
    properties:
      messages:
        type: array
        items:
          type: object
          properties:
            id: string
            content: object

Schema Validation

Triggers support JSON Schema validation for input data. This ensures that workflows only process valid data and fail early if the input doesn’t match the expected format.

trigger:
  type: webhook
  config:
    url: /workflows/analyze-content
    method: POST
  schema:
    type: object
    properties:
      content:
        type: string
        minLength: 1
        maxLength: 10000
      options:
        type: object
        properties:
          language:
            type: string
            enum: [en, es, fr]
          sentiment:
            type: boolean
            default: false
    required: [content]
    additionalProperties: false

Advanced Features

Error Handling

Configure how trigger errors should be handled:

trigger:
  type: webhook
  config:
    url: /workflows/process
    method: POST
  on_error:
    retry:
      attempts: 3
      backoff: exponential
      interval: 1s
    fallback:
      workflow: error-handler

Rate Limiting

Control the rate of workflow executions:

trigger:
  type: webhook
  config:
    url: /workflows/analyze
    method: POST
    rate_limit:
      requests: 100
      period: 1m

Conditional Execution

Add conditions to control when triggers should start workflows:

trigger:
  type: event
  config:
    event: document.updated
  condition: "{{ event.changes.status == 'published' }}"

API Reference

Parameters
JSON Schema

string

required

Type of trigger (webhook, schedule, event, message)

object

required

Trigger-specific configuration

Show Webhook Config

string

required

Endpoint URL for the webhook

string

HTTP method (GET, POST, PUT, etc.)

Show Schedule Config

string

required

Cron expression for scheduling

string

Timezone for the schedule (default: UTC)

Show Event Config

string

required

Event name to listen for

string

Source of the event

Show Message Config

string

required

Queue name or identifier

number

Number of messages to process at once

number

Message visibility timeout in seconds

object

JSON Schema for validating trigger input

object

Error handling configuration

Show Properties

object

number

Number of retry attempts

string

Backoff strategy (linear, exponential)

string

Initial retry interval

object

string

Fallback workflow to execute

object

Rate limiting configuration

Show Properties

number

Maximum number of requests

string

Time period for rate limit

string

Template expression for conditional execution

https://compozy.dev/schemas/triggers.json

{
  "type": "object",
  "required": ["type", "config"],
  "properties": {
    "type": {
      "type": "string",
      "enum": ["webhook", "schedule", "event", "message"],
      "description": "Type of trigger"
    },
    "config": {
      "type": "object",
      "description": "Trigger-specific configuration",
      "oneOf": [
        {
          "type": "object",
          "required": ["url"],
          "properties": {
            "url": {
              "type": "string",
              "description": "Endpoint URL for the webhook"
            },
            "method": {
              "type": "string",
              "enum": ["GET", "POST", "PUT", "DELETE", "PATCH"],
              "default": "POST",
              "description": "HTTP method"
            }
          }
        },
        {
          "type": "object",
          "required": ["cron"],
          "properties": {
            "cron": {
              "type": "string",
              "description": "Cron expression for scheduling"
            },
            "timezone": {
              "type": "string",
              "default": "UTC",
              "description": "Timezone for the schedule"
            }
          }
        },
        {
          "type": "object",
          "required": ["event"],
          "properties": {
            "event": {
              "type": "string",
              "description": "Event name to listen for"
            },
            "source": {
              "type": "string",
              "description": "Source of the event"
            }
          }
        },
        {
          "type": "object",
          "required": ["queue"],
          "properties": {
            "queue": {
              "type": "string",
              "description": "Queue name or identifier"
            },
            "batch_size": {
              "type": "number",
              "description": "Number of messages to process at once"
            },
            "visibility_timeout": {
              "type": "number",
              "description": "Message visibility timeout in seconds"
            }
          }
        }
      ]
    },
    "schema": {
      "type": "object",
      "description": "JSON Schema for validating trigger input"
    },
    "on_error": {
      "type": "object",
      "properties": {
        "retry": {
          "type": "object",
          "properties": {
            "attempts": {
              "type": "number",
              "description": "Number of retry attempts"
            },
            "backoff": {
              "type": "string",
              "enum": ["linear", "exponential"],
              "description": "Backoff strategy"
            },
            "interval": {
              "type": "string",
              "description": "Initial retry interval"
            }
          }
        },
        "fallback": {
          "type": "object",
          "properties": {
            "workflow": {
              "type": "string",
              "description": "Fallback workflow to execute"
            }
          }
        }
      }
    },
    "rate_limit": {
      "type": "object",
      "properties": {
        "requests": {
          "type": "number",
          "description": "Maximum number of requests"
        },
        "period": {
          "type": "string",
          "description": "Time period for rate limit"
        }
      }
    },
    "condition": {
      "type": "string",
      "description": "Template expression for conditional execution"
    }
  }
}

Best Practices

Schema Definition

Always define input schemas
Validate required fields
Set appropriate constraints
Document field purposes

Error Handling

Configure retry policies
Implement fallback mechanisms
Log trigger failures
Monitor trigger health

Security

Use HTTPS for webhooks
Implement authentication
Validate request origins
Sanitize input data

Performance

Set appropriate rate limits
Configure batch sizes
Use efficient schemas
Monitor trigger latency

References

Workflow Usage

Learn how to use triggers in workflows

Tasks API

Understand task configuration

Error Handling

Implement error handling strategies

Schema Reference

Complete trigger schema reference

Getting Started

Core Concepts

Trigger Types

Webhook

Schedule

Event

Message

Configuration

Schema Validation

Advanced Features

Error Handling

Rate Limiting

Conditional Execution

API Reference

Best Practices

References

Workflow Usage

Tasks API

Error Handling

Schema Reference

​Trigger Types

Webhook

Schedule

Event

Message

​Configuration

​Schema Validation

​Advanced Features

​Error Handling

​Rate Limiting

​Conditional Execution

​API Reference

​Best Practices

​References

Workflow Usage

Tasks API

Error Handling

Schema Reference

Trigger Types

Configuration

Schema Validation

Advanced Features

Error Handling

Rate Limiting

Conditional Execution

API Reference

Best Practices

References