Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
| 1 | --- |
| 2 | title: Triggers |
| 3 | description: React to events in connected apps. Composio delivers them to your app as structured payloads. |
| 4 | keywords: [triggers, events, realtime, polling, webhook, concepts] |
| 5 | --- |
| 6 | |
| 7 | When something happens in a connected app (a new Slack message, a GitHub commit, an incoming email), a **trigger** sends that event to your app as a structured payload. You write the handler. Composio handles the connection to the provider, delivery, retries, and signing. |
| 8 | |
| 9 | <TriggersFlow /> |
| 10 | |
| 11 | ## Where events arrive |
| 12 | |
| 13 | Composio delivers every event to one destination you control: your webhook URL. You register it once per project, and Composio `POST`s every trigger event there, signed so you can verify it. |
| 14 | |
| 15 | ## Realtime vs polling |
| 16 | |
| 17 | Under the hood, Composio learns about events in one of two ways. It only affects how quickly an event reaches you. |
| 18 | |
| 19 | | Kind | How Composio learns about the event | Latency | Examples | |
| 20 | |---|---|---|---| |
| 21 | | **Realtime** | The provider pushes the event to Composio the moment it happens. | Near-instant | Slack, Asana, Notion, Outlook, Gmail, Google Calendar | |
| 22 | | **Polling** | Composio checks the provider on a schedule. | Up to the trigger's polling interval, 2 min by default | Google Drive, Google Sheets, OneDrive | |
| 23 | |
| 24 | Most trigger types use one kind. Some, including the Gmail and Google Calendar triggers, support both: Composio uses realtime delivery whenever it can, and you can choose with `type`. See [Choosing webhook or polling](/docs/setting-up-triggers/creating-triggers#choosing-webhook-or-polling). |
| 25 | |
| 26 | Either way, the event lands in the same place: your subscription or webhook URL, in the same payload shape. |
| 27 | |
| 28 | <Callout> |
| 29 | If you **bring your own OAuth app**, some providers only deliver to URLs registered on that app, so you register Composio's ingress URL there once. See [Custom OAuth webhooks](/docs/setting-up-triggers/custom-oauth-webhooks). |
| 30 | </Callout> |
| 31 | |
| 32 | ## Trigger types and instances |
| 33 | |
| 34 | A **trigger type** is a kind of event you can listen for, like `GITHUB_COMMIT_EVENT` or a new Slack message. Each toolkit has its own set. |
| 35 | |
| 36 | A **trigger instance** is a trigger type you've activated for one [user's connected account](/docs/how-composio-works). It has its own `ti_*` ID that you can enable, disable, or delete independently. |
| 37 | |
| 38 | ## Working with triggers |
| 39 | |
| 40 | 0. **Authenticate** the user for the toolkit: an [auth config](/docs/authentication#behind-the-scenes) and a [connected account](/docs/authentication). See [Authentication](/docs/authentication). |
| 41 | 1. **Create** a trigger for the user's connected account. See [Creating triggers](/docs/setting-up-triggers/creating-triggers). |
| 42 | 2. **Receive** its events: locally with `subscribe()`, or in production at your webhook URL. See [Receiving events](/docs/setting-up-triggers/subscribing-to-events). |
| 43 | 3. **Manage** triggers: enable, disable, or delete. See [Managing triggers](/docs/setting-up-triggers/managing-triggers). |
| 44 | |
| 45 | ## Next |
| 46 | |
| 47 | <Card icon={<Plug />} title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Activate a trigger for a user so events start flowing" /> |