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]

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

type

string

required

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

config

object

required

Trigger-specific configuration

Show Webhook Config

url

string

required

Endpoint URL for the webhook

method

string

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

Show Schedule Config

cron

string

required

Cron expression for scheduling

timezone

string

Timezone for the schedule (default: UTC)

Show Event Config

event

string

required

Event name to listen for

source

string

Source of the event

Show Message Config

queue

string

required

Queue name or identifier

batch_size

number

Number of messages to process at once

visibility_timeout

number

Message visibility timeout in seconds

schema

object

JSON Schema for validating trigger input

on_error

object

Error handling configuration

Show Properties

retry

object

attempts

number

Number of retry attempts

backoff

string

Backoff strategy (linear, exponential)

interval

string

Initial retry interval

fallback

object

workflow

string

Fallback workflow to execute

rate_limit

object

Rate limiting configuration

Show Properties

requests

number

Maximum number of requests

period

string

Time period for rate limit

condition

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

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

Configuration

Schema Validation

Advanced Features

Error Handling

Rate Limiting

Conditional Execution

API Reference

Best Practices

References