Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
Mirrored from https://github.com/Camo67/composio.git
Synced Nov 22, 23:15 UTC
docs: restructure trigger docs
balyan.sid@gmail.com committed
Jun 25, 2025 at 20:10 UTC
fae600d175428a159452dbc7c55a27b3e95c55a9
4 files changed
+142
-175
fern/docs.yml
+1
-1
@@ -239,7 +239,7 @@ navigation:
239
slug: providers/custom/python
240
- tab: tools
241
layout:
242
- - section: Tools
242
+ - section: Tool
243
contents:
244
- page: Introduction
245
path: tools/introduction.mdx
fern/pages/src/triggers/using-triggers.mdx
+64
-125
@@ -1,28 +1,30 @@
1
---
2
title: Using Triggers
3
-subtitle: Send payloads to your system based on external events
3
+subtitle: Send payloads to your AI agents or systems based on events in apps.
4
image: "https://og.composio.dev/api/og?title=Using%20Triggers" # image for socials
5
keywords: ''
6
hide-nav-links: true
7
---
8
9
-Triggers act as a notification system for your AI applications, enabling your agents to respond dynamically to external events occurring within your integrations.
9
+Triggers act as a notification system for your AI applications, enabling your agents to respond dynamically to external events occurring within your apps.
10
11
-When these events take place, triggers capture relevant information and deliver structured payloads directly to your system, facilitating timely and context-aware responses.
11
+
12
+When these events take place, triggers capture relevant information and deliver structured payloads directly to your system, letting you build agents that respond proactively.
13
14
<Frame caption="Triggers through Composio" background="subtle">
15

16
</Frame>
17
18
<Tip title="Prerequisites">
18
- Before proceeding, ensure you've created an auth config and established a connection to your
19
- external account (e.g., Slack, GitHub).
19
+ Before proceeding, ensure you've created an [auth config](/docs/authenticating-tools#creating-an-auth-config) and [established a connection](/docs/authenticating-tools#connecting-to-an-oauth-toolkit) to an app (e.g., Slack, GitHub).
20
</Tip>
21
22
## Creating a trigger
23
24
Head to the any app that supports triggers, eg [Slack](https://app.composio.dev/app/slack) in the dashboard and enable the trigger of choice.
25
26
+<Tabs>
27
+<Tab title="Dashboard">
28
<video
29
src="../../../assets/videos/enabling-triggers.mp4"
30
width="854"
@@ -33,99 +35,91 @@ Head to the any app that supports triggers, eg [Slack](https://app.composio.dev/
35
controls
36
></video>
37
36
-The [triggers page](https://app.composio.dev/active_triggers?page=1) will show you all the triggers that are enabled for your account.
37
-
38
<Frame caption="Triggers page" background="subtle">
39
<img src="../../../assets/images/manage-triggers.png" alt="Manage triggers" />
40
</Frame>
41
42
-You create triggers through the SDK as well.
42
+In some cases, triggers require certain configuration to set the correct events. You can inspect and add these properties while enabling the triggers.
43
44
-First, you can view the required configuration to make the trigger too as follows:
44
+The dashboard will show you the trigger configuration to fill in.
45
+
46
+<Frame caption="Trigger configuration" background="subtle">
47
+ <img
48
+ src="../../../assets/images/trigger-config.png"
49
+ alt="Trigger configuration"
50
+ width="400px"
51
+ height="auto"
52
+ />
53
+</Frame>
54
+
55
+
56
+</Tab>
57
+<Tab title="SDK">
58
+You create triggers through the SDK as well.
59
60
<CodeGroup>
61
<SnippetCode
48
- src="fern/snippets/triggers/typescript/triggers.ts"
62
+ src="fern/snippets/triggers/python/triggers.py"
63
+ title="Python"
64
startLine={1}
50
- endLine={27}
51
- title="TypeScript (new)"
65
+ endLine={12}
66
+ highlightStart={10}
67
+ highlightEnd={10}
68
/>
69
54
-</CodeGroup>
55
-
56
-To create a trigger, first fetch the user's connection ID, then use it along with the required configuration.
57
-
58
-<CodeGroup>
59
-```python Python
60
-instance = composio.triggers.create(
61
- slug="GITHUB_COMMIT_EVENT",
62
- connected_account_id="ca_abc1234",
63
- trigger_config={
64
- "repo": "composio",
65
- "owner": "composiohq",
66
- },
67
-)
68
-print(instance)
69
-```
70
<SnippetCode
71
src="fern/snippets/triggers/typescript/triggers.ts"
72
- startLine={28}
73
- endLine={40}
74
- title="TypeScript (new)"
72
+ startLine={1}
73
+ endLine={13}
74
+ highlightStart={8}
75
+ highlightEnd={11}
76
+ title="TypeScript"
77
/>
78
</CodeGroup>
79
80
79
-## Subscribing to triggers using the SDK (for development)
80
-During development, you may not have a proper webhook setup -- so you can subscribe to triggers directly through the SDK.
81
+Most triggers require certain configuration to send the correct events. For example, `GITHUB_COMMIT_EVENT` requires you to specify the repository and owner.
82
82
-You subscribe to multiple trigger events by configuring the filters.
83
-When you specify multiple multiple filters, _ALL_ of them must match for the trigger to be subscribed to.
84
-
85
-This method uses websockets to subscribe to the trigger.
83
+**Fetch required trigger configuration**
84
85
<CodeGroup>
88
-```python Python
89
-# Fetch connected account for user
90
-user_id = "user@acme.com"
91
-connected_accounts = composio.connected_accounts.list(user_ids=[user_id], limit=1).items
92
-if len(connected_accounts) == 0:
93
- raise ValueError("No connected account found")
94
-
95
-# Get the first connected account
96
-connected_account = connected_accounts[0]
97
-
98
-# Create a trigger instance
99
-instance = composio.triggers.create(
100
- slug="GITHUB_COMMIT_EVENT",
101
- connected_account_id=connected_account.id,
102
- trigger_config={
103
- "repo": "composio",
104
- "owner": "composiohq",
105
- },
106
-)
107
-print(instance)
108
-```
109
-
86
<SnippetCode
111
-src="fern/snippets/triggers/typescript/triggers.ts"
112
-startLine={42}
113
-endLine={53}
114
-title="TypeScript (new)"
87
+ src="fern/snippets/triggers/python/triggers.py"
88
+ startLine={13}
89
+ endLine={32}
90
+ title="Python"
91
/>
92
93
+<SnippetCode
94
+ src="fern/snippets/triggers/typescript/triggers.ts"
95
+ startLine={14}
96
+ endLine={35}
97
+ title="TypeScript"
98
+/>
99
</CodeGroup>
100
+</Tab>
101
+</Tabs>
102
+
103
+The [triggers page](https://app.composio.dev/active_triggers?page=1) will show you all the triggers that are enabled for your account.
104
+
105
+
106
+## Subscribing to triggers
107
+The typical and recommended way to subscribe to triggers is through webhooks.
108
109
120
-## Subscribing to triggers through Webhooks
110
To receive trigger events via webhooks, you need to configure a publicly accessible URL where Composio can send the event payloads. This URL should point to an endpoint in your application that can process incoming webhook requests.
111
112
+<Tip title="Use ngrok/webhook.site for local dev!">
113
+During development, you can use ngrok/webhook.site or other services to expose your local server to the internet.
114
+</Tip>
115
+
116
<Frame caption="Webhook setup" background="subtle">
117
<img src="../../../assets/images/setup-webhook.png" alt="Webhook setup" />
118
</Frame>
119
127
-<CodeGroup>
120
+Below are some examples of how to listen in on trigger events for a FastAPI/Next.js application.
121
122
+<CodeGroup>
123
<SnippetCode
124
src="fern/snippets/triggers/python/trigger-webhook.py"
125
title="app/route.py"
@@ -135,10 +129,9 @@ To receive trigger events via webhooks, you need to configure a publicly accessi
129
src="fern/snippets/triggers/typescript/trigger-webhook.ts"
130
title="app/api/webhook/route.ts"
131
/>
138
-
132
</CodeGroup>
133
141
-### Trigger payload types
134
+## Trigger payload types
135
When subscribing to triggers, it is helpful to know the payload type recieved from the trigger. You can inspect the payload type by fetching the trigger type.
136
137
<CodeGroup>
@@ -156,16 +149,15 @@ console.log(triggerType.payload);
149
150
</CodeGroup>
151
159
-## Subscribing to triggers through the SDK
160
-
161
-During development you may not have a proper webhook setup -- you can subscribe to triggers directly through the SDK.
152
163
-This uses websockets to subscribe to the trigger.
153
+## Prototyping triggers during development
154
+During prototyping you may not have a proper server setup -- so you can subscribe to triggers directly through the SDK for small scripts.
155
156
You subscribe to multiple trigger events by configuring the filters.
166
-
157
When you specify multiple multiple filters, _ALL_ of them must match for the trigger to be subscribed to.
158
159
+This uses websockets to subscribe to the trigger. When you specify multiple multiple filters, _ALL_ of them must match for the trigger to be subscribed to.
160
+
161
<CodeGroup>
162
```python Python maxLines=60 wordWrap
163
user_id = "user@email.com"
@@ -194,59 +186,6 @@ await composio.triggers.subscribe(
186
```
187
</CodeGroup>
188
197
-## Specifying trigger configuration
198
-
199
-In some cases, triggers require certain configuration to set the correct events. You can inspect and add these properties while enabling the triggers.
200
-
201
-The dashboard will show you the trigger configuration to fill in.
202
-
203
-<Frame caption="Trigger configuration" background="subtle">
204
- <img
205
- src="../../../assets/images/trigger-config.png"
206
- alt="Trigger configuration"
207
- width="400px"
208
- height="auto"
209
- />
210
-</Frame>
211
-
212
-<CodeGroup>
213
-```python Python maxLines=60 wordWrap
214
-# Get a trigger by id
215
-trigger = composio.triggers.get_type(slug="GITHUB_COMMIT_EVENT")
216
-print(trigger.config)
217
-```
218
-
219
-```typescript TypeScript maxLines=60 wordWrap
220
-const triggerType = await composio.triggers.getType("GITHUB_STAR_ADDED_EVENT");
221
-
222
-console.log(triggerType.config);
223
-
224
-```
225
-
226
-</CodeGroup>
227
-
228
-<CodeGroup>
229
-```python Python maxLines=60 wordWrap
230
-instance = composio.triggers.create(
231
- slug="GITHUB_PULL_REQUEST_EVENT",
232
- connected_account_id="ca_abc1234",
233
- trigger_config={
234
- "repo": "composio",
235
- "owner": "composiohq",
236
- },
237
-)
238
-```
239
-```typescript TypeScript maxLines=60 wordWrap
240
-await composio.triggers.create("GITHUB_PULL_REQUEST_EVENT", {
241
- connectedAccountId: "ca_k_py8Qbd17_d",
242
- triggerConfig: { // Properties expected for trigger config
243
- owner: "composiohq",
244
- repo: "composio",
245
- },
246
-});
247
-```
248
-</CodeGroup>
249
-
189
## Enabling/Disabling triggers
190
191
In cases where the trigger isn't required for the system, it can be disabled.
fern/snippets/triggers/python/triggers.py
+28
-2
@@ -2,6 +2,32 @@ from composio import Composio
2
3
composio = Composio()
4
5
-trigger = composio.triggers.get("GITHUB_STAR_ADDED_EVENT")
5
+user_id = "user@example.com"
6
7
-print(trigger)
\ No newline at end of file
7
+trigger = composio.triggers.create(
8
+ slug="GITHUB_COMMIT_EVENT",
9
+ user_id=user_id,
10
+ trigger_config={"repo": "composiohq", "owner": "composio"},
11
+)
12
+print(trigger)
13
+
14
+trigger_config = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
15
+print(trigger_config.config)
16
+### Trigger Config
17
+# {
18
+# "properties": {
19
+# "owner": {
20
+# "description": "Owner of the repository",
21
+# "title": "Owner",
22
+# "type": "string"
23
+# },
24
+# "repo": {
25
+# "description": "Repository name",
26
+# "title": "Repo",
27
+# "type": "string"
28
+# }
29
+# },
30
+# "required": ["owner", "repo"],
31
+# "title": "WebhookConfigSchema",
32
+# "type": "object"
33
+# }
\ No newline at end of file
fern/snippets/triggers/typescript/triggers.ts
+49
-47
@@ -1,56 +1,58 @@
1
-import { Composio } from "@composio/core";
1
+import { Composio } from '@composio/core';
2
3
-const composio = new Composio()
3
+const composio = new Composio();
4
5
-composio.triggers.getType("GITHUB_STAR_ADDED_EVENT").then(triggerType => {
6
- console.log(JSON.stringify(triggerType.config, null, 2))
7
-})
8
-// {
9
-// "properties": {
10
-// "owner": {
11
-// "description": "Owner of the repository",
12
-// "title": "Owner",
13
-// "type": "string"
14
-// },
15
-// "repo": {
16
-// "description": "Repository name",
17
-// "title": "Repo",
18
-// "type": "string"
19
-// }
20
-// },
21
-// "required": [
22
-// "owner",
23
-// "repo"
24
-// ],
25
-// "title": "WebhookConfigSchema",
26
-// "type": "object"
27
-// }
5
+const userId = 'user@acme.com';
6
29
-const userId = "user@acme.com";
30
-const { items: connections } = await composio.connectedAccounts.list({ userIds: [userId] });
31
-const [{ id: connectedAccountId }] = connections;
32
-console.log(connectedAccountId);
33
-const createResponse = await composio.triggers.create("GITHUB_STAR_ADDED_EVENT", {
34
- connectedAccountId,
7
+const createResponse = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {
8
triggerConfig: {
36
- owner: "composiohq",
37
- repo: "composio",
9
+ owner: 'composiohq',
10
+ repo: 'composio',
11
},
12
});
40
-
41
-
42
-await composio.triggers.subscribe(
43
- triggerData => {
44
- console.log('Received trigger:', triggerData);
13
+console.log(createResponse);
14
+// Fetch the trigger details
15
+const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
16
+console.log(JSON.stringify(triggerType.config, null, 2));
17
+/*--- Trigger config ---
18
+{
19
+ "properties": {
20
+ "owner": {
21
+ "description": "Owner of the repository",
22
+ "title": "Owner",
23
+ "type": "string"
24
},
46
- {
47
- // triggerId: 'ti_9q19nLNykmVZ',
48
- // toolkits: ['GITHUB']
49
- // userId: "sid",
50
- // triggerSlug: ["GITHUB_STAR_ADDED_EVENT"]
51
- authConfigId: "ac_1234567890"
25
+ "repo": {
26
+ "description": "Repository name",
27
+ "title": "Repo",
28
+ "type": "string"
29
}
53
-)
30
+ },
31
+ "required": ["owner", "repo"],
32
+ "title": "WebhookConfigSchema",
33
+ "type": "object"
34
+}
35
+*/
36
55
-await composio.triggers.enable("ti_9q19nLNykmVZ")
56
-await composio.triggers.disable("ti_9q19nLNykmVZ")
\ No newline at end of file
37
+// Fetch the connected account for the user
38
+const { items: connections } = await composio.connectedAccounts.list({
39
+ userIds: [userId],
40
+});
41
+// Get the first connected account
42
+const [{ id: connectedAccountId }] = connections;
43
+
44
+// Create the trigger
45
+await composio.triggers.subscribe(
46
+ triggerData => {
47
+ console.log('Received trigger:', triggerData);
48
+ },
49
+ {
50
+ // triggerId: 'ti_9q19nLNykmVZ',
51
+ // toolkits: ['GITHUB']
52
+ // userId: "sid",
53
+ // triggerSlug: ["GITHUB_STAR_ADDED_EVENT"]
54
+ authConfigId: 'ac_1234567890',
55
+ }
56
+);
57
+await composio.triggers.enable('ti_9q19nLNykmVZ');
58
+await composio.triggers.disable('ti_9q19nLNykmVZ');