Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
mdx 47 lines 3.02 KB
Raw
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" />