> ## Documentation Index
> Fetch the complete documentation index at: https://docs.compozy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Triggers

> Triggers define how and when workflows start executing. They specify the entry point for your workflow and define the schema for input data. Compozy supports several types of triggers to accommodate different use cases and integration needs.

## Trigger Types

<CardGroup cols={2}>
  <Card title="Webhook" icon="globe">
    HTTP endpoints that start workflows when called
  </Card>

  <Card title="Schedule" icon="clock">
    Time-based triggers using cron expressions
  </Card>

  <Card title="Event" icon="bolt">
    React to system or custom events
  </Card>

  <Card title="Message" icon="message">
    Process messages from queues or streams
  </Card>
</CardGroup>

## Configuration

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

<CodeGroup>
  ```yaml Webhook theme={"dark"}
  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]
  ```

  ```yaml Schedule theme={"dark"}
  trigger:
    type: schedule
    config:
      cron: "0 0 * * *"  # Daily at midnight
      timezone: UTC
    schema:
      type: object
      properties:
        timestamp:
          type: string
          format: date-time
  ```

  ```yaml Event theme={"dark"}
  trigger:
    type: event
    config:
      event: document.created
      source: document-service
    schema:
      type: object
      properties:
        documentId:
          type: string
        version:
          type: string
      required: [documentId]
  ```

  ```yaml Message theme={"dark"}
  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
  ```
</CodeGroup>

## 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.

```yaml theme={"dark"}
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:

```yaml theme={"dark"}
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:

```yaml theme={"dark"}
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:

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

## API Reference

<Tabs>
  <Tab title="Parameters">
    <ParamField path="type" type="string" required>
      Type of trigger (webhook, schedule, event, message)
    </ParamField>

    <ParamField path="config" type="object" required>
      Trigger-specific configuration

      <Expandable title="Webhook Config">
        <ParamField path="url" type="string" required>
          Endpoint URL for the webhook
        </ParamField>

        <ParamField path="method" type="string">
          HTTP method (GET, POST, PUT, etc.)
        </ParamField>
      </Expandable>

      <Expandable title="Schedule Config">
        <ParamField path="cron" type="string" required>
          Cron expression for scheduling
        </ParamField>

        <ParamField path="timezone" type="string">
          Timezone for the schedule (default: UTC)
        </ParamField>
      </Expandable>

      <Expandable title="Event Config">
        <ParamField path="event" type="string" required>
          Event name to listen for
        </ParamField>

        <ParamField path="source" type="string">
          Source of the event
        </ParamField>
      </Expandable>

      <Expandable title="Message Config">
        <ParamField path="queue" type="string" required>
          Queue name or identifier
        </ParamField>

        <ParamField path="batch_size" type="number">
          Number of messages to process at once
        </ParamField>

        <ParamField path="visibility_timeout" type="number">
          Message visibility timeout in seconds
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="schema" type="object">
      JSON Schema for validating trigger input
    </ParamField>

    <ParamField path="on_error" type="object">
      Error handling configuration

      <Expandable title="Properties">
        <ParamField path="retry" type="object">
          <ParamField path="attempts" type="number">
            Number of retry attempts
          </ParamField>

          <ParamField path="backoff" type="string">
            Backoff strategy (linear, exponential)
          </ParamField>

          <ParamField path="interval" type="string">
            Initial retry interval
          </ParamField>
        </ParamField>

        <ParamField path="fallback" type="object">
          <ParamField path="workflow" type="string">
            Fallback workflow to execute
          </ParamField>
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="rate_limit" type="object">
      Rate limiting configuration

      <Expandable title="Properties">
        <ParamField path="requests" type="number">
          Maximum number of requests
        </ParamField>

        <ParamField path="period" type="string">
          Time period for rate limit
        </ParamField>
      </Expandable>
    </ParamField>

    <ParamField path="condition" type="string">
      Template expression for conditional execution
    </ParamField>
  </Tab>

  <Tab title="JSON Schema">
    ```json https://compozy.dev/schemas/triggers.json [expandable] theme={"dark"}
    {
      "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"
        }
      }
    }
    ```
  </Tab>
</Tabs>

## Best Practices

<Steps>
  <Step title="Schema Definition">
    * Always define input schemas
    * Validate required fields
    * Set appropriate constraints
    * Document field purposes
  </Step>

  <Step title="Error Handling">
    * Configure retry policies
    * Implement fallback mechanisms
    * Log trigger failures
    * Monitor trigger health
  </Step>

  <Step title="Security">
    * Use HTTPS for webhooks
    * Implement authentication
    * Validate request origins
    * Sanitize input data
  </Step>

  <Step title="Performance">
    * Set appropriate rate limits
    * Configure batch sizes
    * Use efficient schemas
    * Monitor trigger latency
  </Step>
</Steps>

## References

<CardGroup cols={2}>
  <Card title="Workflow Usage" icon="book" href="/core/workflows/usage">
    Learn how to use triggers in workflows
  </Card>

  <Card title="Tasks API" icon="code" href="/core/tasks/api">
    Understand task configuration
  </Card>

  <Card title="Error Handling" icon="shield" href="/core/tasks/error-handling">
    Implement error handling strategies
  </Card>

  <Card title="Schema Reference" icon="file-code" href="/core/base-structure/api#triggers">
    Complete trigger schema reference
  </Card>
</CardGroup>