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

# Triggers

> Start Twin agents automatically

Triggers let Twin agents run without manual input — either when something happens in another app or on a defined schedule.

## Overview

Triggers are how agents move from "on-demand" to fully autonomous.

With triggers, an agent can:

* Start immediately when an external event occurs
* Run automatically at fixed intervals
* Be triggered programmatically from your own backend

<CardGroup cols={3}>
  <Card title="Event-based triggers" icon="bell" color="#F4D03F">
    Agents react to incoming events from other apps
  </Card>

  <Card title="Time-based triggers" icon="clock" color="#F4D03F">
    Agents run on a defined schedule
  </Card>

  <Card title="REST API" icon="code" color="#F4D03F">
    Trigger agents from your own backend via API
  </Card>
</CardGroup>

Both allow Twin to operate continuously in the background.

## Event-Based Triggers

Event-based triggers launch an agent as soon as something happens in another system — for example, when a message arrives or new data is created.

### Built-in Event Sources

Twin supports direct connections to common communication and productivity tools. Once an account is connected, events from that tool can be used to start an agent automatically.

<Card title="Examples" icon="plug" color="#F4D03F">
  * New messages or activity in Slack
  * Updates in GDrive or Attio
  * Changes in Intercom or internal tools
</Card>

### External App Events

Twin can also react to events from a wide range of third-party services via event platforms and connectors.

This makes it possible to trigger agents from thousands of applications, including:

<CardGroup cols={2}>
  <Card title="Gmail" icon="envelope" color="#F4D03F">
    New emails, label changes, or draft creation
  </Card>

  <Card title="Google Calendar" icon="calendar" color="#F4D03F">
    Event creation, updates, or deletions
  </Card>

  <Card title="GitHub" icon="github" color="#F4D03F">
    Code pushes, new issues, pull requests
  </Card>

  <Card title="Notion" icon="file-lines" color="#F4D03F">
    Page or database updates
  </Card>
</CardGroup>

Also supports **HubSpot, Stripe, Airtable**, and many more.

If your app supports event-based actions, Twin can likely trigger from it.

### Custom Webhooks

For systems that aren't supported out of the box, Twin can expose **custom webhook endpoints**.

These endpoints accept structured HTTP requests and can be called from:

* Internal services
* Custom applications
* Scripts
* Any platform capable of sending JSON payloads

You simply specify what system should call the webhook and what data it will send — Twin handles the rest.

## Setting Up Event Triggers

<Steps>
  <Step title="Connect the source system" icon="link" color="#F4D03F">
    Link the tool or service that will emit the event.
  </Step>

  <Step title="Define the triggering condition" icon="filter" color="#F4D03F">
    Specify what should start the agent (for example, "a new message is received" or "a record is created").
  </Step>

  <Step title="Review and activate" icon="check" color="#F4D03F">
    Once configured, the trigger becomes active and will start the agent automatically when the condition is met.
  </Step>
</Steps>

You can see and manage active triggers from your agent settings.

## Scheduled Triggers

Scheduled triggers run agents at predefined times, regardless of external events.

This is useful for:

<CardGroup cols={2}>
  <Card title="Data Collection" icon="database" color="#F4D03F">
    Recurring data gathering tasks
  </Card>

  <Card title="Reports" icon="chart-bar" color="#F4D03F">
    Daily or weekly automated reports
  </Card>

  <Card title="Monitoring" icon="eye" color="#F4D03F">
    Regular monitoring tasks
  </Card>

  <Card title="Maintenance" icon="wrench" color="#F4D03F">
    Routine maintenance workflows
  </Card>
</CardGroup>

### Creating a Schedule

<Steps>
  <Step title="Verify the agent" icon="flask" color="#F4D03F">
    Make sure the agent runs correctly when executed manually.
  </Step>

  <Step title="Choose a schedule" icon="calendar-days" color="#F4D03F">
    Select how often it should run — hourly, daily, weekly, or a custom interval.
  </Step>

  <Step title="Activate the schedule" icon="power-off" color="#F4D03F">
    Once saved, the agent will run automatically based on the defined timing.
  </Step>

  <Step title="Manage schedules" icon="sliders" color="#F4D03F">
    All active schedules can be viewed and adjusted from the scheduling dashboard.
  </Step>
</Steps>

## REST API Triggers

If you're a developer, you can trigger Twin agents directly from your own backend using the [REST API](/rest-api). This lets you integrate Twin into any existing application or workflow.

```bash theme={null}
curl -X POST https://build.twin.so/v1/agents/agent_abc123/runs \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"run_mode": "run", "user_message": "Run now"}'
```

Use API triggers when you want to:

* Run agents in response to events in your own system
* Integrate Twin into a custom pipeline or CI/CD flow
* Build a product where Twin agents power backend logic

<Card title="REST API Reference" icon="code" href="/rest-api" color="#F4D03F">
  See the full API documentation for triggering runs, managing agents, and more
</Card>

## Choosing the Right Trigger

| Scenario                                 | Recommended Trigger |
| ---------------------------------------- | ------------------- |
| React immediately to messages or updates | Event-based trigger |
| Run recurring jobs or reports            | Scheduled trigger   |
| Integrate with unsupported systems       | Webhook trigger     |
| Trigger from your own backend            | REST API            |

**Event-based triggers** are ideal when speed matters.

**Scheduled triggers** are best for predictable, recurring work.

**REST API** is best for developers integrating Twin into existing systems.

<Card title="Start Building" icon="arrow-right" href="https://builder.twin.so/" color="#F4D03F">
  Set up your first trigger in the Twin App
</Card>