@devries-cameron20 / composio Mirror · read-only / commits / fd9367df9
Fork 0

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, 20:45 UTC

Update to triggers page in docs (#1906)

Sushmitha Mallesh committed Sep 9, 2025 at 10:32 UTC fd9367df961d5c8bde1a04f5c5a23c2367b854ec
10 files changed +163 -205
fern/assets/images/manage-triggers.png
Binary files a/fern/assets/images/manage-triggers.png and /dev/null differ
fern/assets/images/trigger-config.png
Binary files a/fern/assets/images/trigger-config.png and b/fern/assets/images/trigger-config.png differ
fern/assets/images/trigger-debug.png
Binary files a/fern/assets/images/trigger-debug.png and /dev/null differ
fern/assets/images/trigger-enable-disable.png
Binary files /dev/null and b/fern/assets/images/trigger-enable-disable.png differ
fern/assets/videos/enabling-triggers.mp4
Binary files a/fern/assets/videos/enabling-triggers.mp4 and b/fern/assets/videos/enabling-triggers.mp4 differ
fern/pages/src/triggers/using-triggers.mdx
+100 -125
@@ -1,120 +1,99 @@
1 ---
2 title: Using Triggers
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: ''
4 +image: 'https://og.composio.dev/api/og?title=Using%20Triggers' # image for socials
5 +keywords: 'triggers, webhooks, websockets, events, active triggers'
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 apps.
9 +When **events** occur in connected apps (like new Slack messages or GitHub commits), triggers automatically send the event data to your application.
10
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.
11 +Each event is delivered as a **structured payload** to your webhook endpoint (via webhooks or WebSockets), enabling your applications or AI agents to respond proactively.
12
13 <Frame caption="Triggers through Composio" background="subtle">
14 ![Triggers Overview](../../../assets/images/triggers.png)
15 </Frame>
16
17 <Tip title="Prerequisites">
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).
18 + Before proceeding, ensure you've created an [auth
19 + config](/docs/authenticating-tools#creating-an-auth-config) and [established a
20 + connection](/docs/authenticating-tools#oauth-connections) to an app (e.g., Slack, GitHub).
21 </Tip>
22
23 ## Creating a trigger
24
24 -Head to any app that supports triggers, such as <a href="https://platform.composio.dev?next_page=/marketplace/slack" target="_blank">Slack</a> in the dashboard and enable the trigger of choice.
25 +You can create triggers using either the Composio dashboard or programmatically via the SDK.
26 +
27 <Tabs>
28 <Tab title="Dashboard">
27 -<video
28 - src="../../../assets/videos/enabling-triggers.mp4"
29 - width="854"
30 - height="480"
31 - autoplay
32 - loop
33 - playsinline
34 - controls
35 -></video>
36 -
37 -<Frame caption="Triggers page" background="subtle">
38 - <img src="../../../assets/images/manage-triggers.png" alt="Manage triggers" />
39 -</Frame>
40 -
41 -In some cases, triggers require certain configuration to set the correct events. You can inspect and add these properties while enabling the triggers.
42 -
43 -The dashboard will show you the trigger configuration to fill in.
44 -
45 -<Frame caption="Trigger configuration" background="subtle">
29 +To create triggers through the **dashboard**:
30 +
31 +- Navigate to the <a href="https://platform.composio.dev?next_page=%2Fauth-configs" target="_blank">Auth Configs</a> page
32 +- Select the auth config
33 +- Click "Add Trigger" and navigate to "Active Triggers" tab to fetch the trigger ID.
34 + <video
35 + src="../../../assets/videos/enabling-triggers.mp4"
36 + width="854"
37 + height="480"
38 + autoplay
39 + loop
40 + playsinline
41 + controls
42 + ></video>
43 +
44 +Some triggers require additional configuration. The dashboard will prompt you for any required fields during setup.
45 +
46 +<Frame caption="Example: Gmail trigger configuration" background="subtle">
47 <img
48 src="../../../assets/images/trigger-config.png"
48 - alt="Trigger configuration"
49 + alt="Trigger configuration example"
50 width="400px"
51 height="auto"
52 />
53 </Frame>
54
54 -
55 </Tab>
56 <Tab title="SDK">
57 -You can also create triggers programmatically using the SDK. To get started, first view the required configuration for creating a trigger:
58 -
57 +Create triggers programmatically by providing the trigger type and any required configuration.
58 <CodeGroup>
59 <SnippetCode
60 src="fern/snippets/triggers/python/triggers.py"
61 title="Python"
62 startLine={1}
64 - endLine={12}
65 - highlightStart={10}
66 - highlightEnd={10}
63 + endLine={18}
64 + highlightStart={12}
65 + highlightEnd={16}
66 />
67
68 <SnippetCode
69 src="fern/snippets/triggers/typescript/triggers.ts"
70 startLine={1}
72 - endLine={13}
73 - highlightStart={8}
74 - highlightEnd={11}
71 + endLine={22}
72 + highlightStart={12}
73 + highlightEnd={21}
74 title="TypeScript"
75 />
76 </CodeGroup>
77
79 -
80 -Most triggers require certain configuration to send the correct events. For example, `GITHUB_COMMIT_EVENT` requires you to specify the repository and owner.
81 -
82 -**Fetch required trigger configuration**
83 -
84 -<CodeGroup>
85 -<SnippetCode
86 - src="fern/snippets/triggers/python/triggers.py"
87 - startLine={13}
88 - endLine={32}
89 - title="Python"
90 -/>
91 -
92 -<SnippetCode
93 - src="fern/snippets/triggers/typescript/triggers.ts"
94 - startLine={5}
95 - endLine={29}
96 - title="TypeScript"
97 -/>
98 -</CodeGroup>
78 </Tab>
79 </Tabs>
80
102 -
81 ## Subscribing to triggers
104 -The typical and recommended way to subscribe to triggers is through webhooks.
82
83 +### Webhooks
84
107 -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.
85 +The recommended way to subscribe to triggers is through webhooks. Configure your webhook URL in the [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events).
86
109 -<Tip title="Use ngrok/webhook.site for local dev!">
110 -During development, you can use ngrok/webhook.site or other services to expose your local server to the internet.
111 -</Tip>
87 +Use a publicly accessible URL where Composio can send event payloads. This endpoint should be able to process incoming POST requests containing the trigger data.
88
113 -<Frame caption="Webhook setup" background="subtle">
114 - <img src="../../../assets/images/setup-webhook.png" alt="Webhook setup" />
115 -</Frame>
89 +<Tip>
90 + **Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to
91 + expose your local server to the internet for testing.
92 +</Tip>
93 +**Implement your webhook handler:**
94
117 -Below are some examples of how to listen in on trigger events for a FastAPI/Next.js application.
95 +Below are some examples of how to listen in on trigger events
96 +for a FastAPI/Next.js application.
97
98 <CodeGroup>
99 <SnippetCode
@@ -128,18 +107,31 @@ Below are some examples of how to listen in on trigger events for a FastAPI/Next
107 />
108 </CodeGroup>
109
110 +### Prototyping with trigger subscriptions
111 +
112 +During development, you can subscribe to triggers directly through the SDK without setting up webhooks.
113 +
114 +You can subscribe to **multiple** trigger events by **configuring the filters**. When you specify multiple filters, ALL of them must match for the trigger to be subscribed to.
115 +
116 +<CodeGroup>
117 + <SnippetCode src="fern/snippets/triggers/python/trigger-subscription.py" title="Python" />
118 + <SnippetCode src="fern/snippets/triggers/typescript/trigger-subscription.ts" title="Typescript" />
119 +</CodeGroup>
120 +
121 ## Trigger payload types
132 -When subscribing to triggers, it is helpful to know the payload type received from the trigger. You can inspect the payload type by fetching the trigger type.
122 +
123 +To see what data you'll receive in your webhook handler, inspect the trigger's payload:
124
125 <CodeGroup>
126 ```python Python maxLines=60 wordWrap
136 -# Get a trigger by id
127 +# Get trigger type to inspect payload structure
128 trigger = composio.triggers.get_type(slug="GITHUB_COMMIT_EVENT")
129 print(trigger.payload)
130 ```
131
132 ```typescript TypeScript maxLines=60 wordWrap
142 -const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
133 +// Get trigger type to inspect payload structure
134 +const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
135
136 console.log(triggerType.payload);
137 ```
@@ -167,80 +159,63 @@ For better type safety and developer experience in TypeScript, you can define sp
159 </CodeGroup>
160
161 This approach provides:
162 +
163 - **IntelliSense support** for trigger payload fields
164 - **Compile-time error checking** for typos and invalid field access
165 - **Better documentation** through TypeScript types
166 - **Improved maintainability** of trigger handling code
167
168 +## Managing triggers
169
176 -## Prototyping triggers during development
177 -During development, you may not have a proper webhook setup -- so you can subscribe to triggers directly through the SDK.
170 +### Enable/disable triggers
171
179 -You subscribe to multiple trigger events by configuring the filters. When you specify multiple filters, ALL of them must match for the trigger to be subscribed to.
172 +You can pause triggers temporarily without deleting them.
173
181 -This method uses WebSocket to subscribe to the trigger.
174 +<Tabs>
175 +<Tab title="Dashboard">
176 +1. Go to the [Auth Config](https://platform.composio.dev?next_page=/auth-configs) page
177 +2. Select your auth config
178 +3. Navigate to "Active Triggers"
179 +4. Disable/Enable the trigger
180
183 -<CodeGroup>
184 -```python Python maxLines=60 wordWrap
185 -user_id = "user@email.com"
181 +<Frame caption="Enable/disable triggers" background="subtle">
182 + <img
183 + src="../../../assets/images/trigger-enable-disable.png"
184 + alt="Enable/disable triggers"
185 + width="400px"
186 + height="auto"
187 + />
188 +</Frame>
189 +</Tab>
190
187 -# Subscribe to a trigger
188 -subscription = composio.triggers.subscribe()
191 +<Tab title="SDK">
192 +<CodeGroup>
193 +```python Python
194 +# Disable a trigger
195 +composio.triggers.disable(trigger_id="ti_abcd123")
196
190 -# Define a handler
191 -@subscription.handle(toolkit="GITHUB", user_id=user_id)
192 -def handle_github_event(data):
193 - print(data)
194 -```
195 -```typescript TypeScript maxLines=60 wordWrap
196 -await composio.triggers.subscribe(
197 - triggerData => {
198 - console.log('Received trigger:', triggerData);
199 - },
200 - {
201 - triggerId: 'ti_So9EQf8XnAcy',
202 - // userId: 'user@acme.com',
203 - // toolkits: ['github', 'slack'],
204 - // triggerSlug: ["GITHUB_STAR_ADDED_EVENT"]
205 - // authConfigId: "ac_1234567890"
206 - }
207 -)
208 -```
209 -</CodeGroup>
197 +# Re-enable when needed
198
211 -## Enabling/Disabling triggers
199 +composio.triggers.enable(trigger_id="ti_abcd123")
200
213 -In cases where the trigger isn't required for the system, it can be disabled.
201 +````
202 +``` typescript TypeScript
203 +// Disable a trigger
204 +await composio.triggers.disable('ti_abcd123');
205
215 -<CodeGroup>
216 - ```python Python maxLines=60 wordWrap
217 - # Disable a trigger instance
218 - disabled_instance = composio.triggers.disable(trigger_id="ti_abcd123")
219 - print(disabled_instance)
220 - ```
221 - ```typescript TypeScript maxLines=60 wordWrap
222 - await composio.triggers.disable("ti_abcd123");
223 - ```
224 -</CodeGroup>
206 +// Re-enable when needed
207 +await composio.triggers.enable('ti_abcd123');
208
226 -If needed, the trigger can be enabled again.
209 +````
210
228 -<CodeGroup>
229 - ```python Python maxLines=60 wordWrap
230 - # Enable a trigger instance
231 - enabled_instance = composio.triggers.enable(trigger_id="ti_abcd123")
232 - print(enabled_instance)
233 - ```
234 - ```typescript TypeScript maxLines=60 wordWrap
235 - await composio.triggers.enable("ti_abcd123");
236 - ```
211 </CodeGroup>
212 +</Tab>
213 +</Tabs>
214
215 ## Troubleshooting
240 -If you encounter issues with triggers or webhook listeners, you can use the Composio dashboard to inspect detailed trigger logs. The dashboard allows you to review event payloads, identify errors, and manually resend events for testing purposes.
216
242 -Access the trigger logs <a href="https://platform.composio.dev?next_page=/logs/triggers" target="_blank">here</a>.
217 +View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).
218
244 -<Frame caption="Trigger logs" background="subtle">
245 - <img src="../../../assets/images/trigger-debug.png" alt="Trigger logs" />
246 -</Frame>
\ No newline at end of file
219 +```
220 +
221 +```
fern/snippets/triggers/python/trigger-subscription.py new
+15
@@ -0,0 +1,15 @@
1 +from composio import Composio
2 +
3 +# Initialize Composio client
4 +composio = Composio(api_key="your_api_key_here")
5 +
6 +# Subscribe to trigger events
7 +subscription = composio.triggers.subscribe()
8 +
9 +# Define event handler
10 +@subscription.handle(trigger_id="your_trigger_id")
11 +def handle_github_commit(data):
12 + print(f"New commit detected: {data}")
13 + # Add your custom logic here
14 +
15 +# Note: For production use, set up webhooks instead
fern/snippets/triggers/python/triggers.py
+9 -24
@@ -1,32 +1,17 @@
1 from composio import Composio
2
3 -composio = Composio()
3 +composio = Composio(api_key="your-api-key")
4 +user_id = "user-id-123435"
5
5 -user_id = "user@example.com"
6 +# Check what configuration is required
7 +trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
8 +print(trigger_type.config)
9 +# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
10
11 +# Create trigger with the required config
12 trigger = composio.triggers.create(
13 slug="GITHUB_COMMIT_EVENT",
14 user_id=user_id,
10 - trigger_config={"repo": "composiohq", "owner": "composio"},
15 + trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
16 )
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"
\ No newline at end of file
17 +print(f"Trigger created: {trigger.trigger_id}")
fern/snippets/triggers/typescript/trigger-subscription.ts new
+20
@@ -0,0 +1,20 @@
1 +import { Composio } from '@composio/core';
2 +
3 +// Initialize Composio client
4 +const composio = new Composio({ apiKey: "your_api_key_here" });
5 +
6 +// Subscribe to trigger events
7 +composio.triggers.subscribe(
8 + (data) => {
9 + console.log(`New commit detected:`, data);
10 + // Add your custom logic here
11 + },
12 + { triggerId: 'your_trigger_id'
13 + // userId: 'user@acme.com',
14 + // toolkits: ['github', 'slack'],
15 + // triggerSlug: ["GITHUB_STAR_ADDED_EVENT"]
16 + // authConfigId: "ac_1234567890" }
17 + }
18 +);
19 +
20 +// Note: For production use, set up webhooks instead
\ No newline at end of file
fern/snippets/triggers/typescript/triggers.ts
+19 -56
@@ -1,59 +1,22 @@
1 import { Composio } from '@composio/core';
2
3 -const composio = new Composio();
4 -const userId = 'user@acme.com';
5 -
6 -// Create the trigger
7 -const createResponse = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {
8 - triggerConfig: {
9 - owner: 'composiohq',
10 - repo: 'composio',
11 - },
12 -});
13 -console.log(createResponse);
14 -
15 -
16 -// Fetch the trigger details
17 -const triggerType = await composio.triggers.getType("GITHUB_STAR_ADDED_EVENT");
18 -console.log(triggerType.config)
19 -/*--- Trigger config ---
20 -{
21 - "properties": {
22 - "owner": {
23 - "description": "Owner of the repository",
24 - "title": "Owner",
25 - "type": "string"
26 - },
27 - "repo": {
28 - "description": "Repository name",
29 - "title": "Repo",
30 - "type": "string"
31 - }
32 - },
33 - "required": [
34 - "owner",
35 - "repo"
36 - ],
37 - "title": "WebhookConfigSchema",
38 - "type": "object"
39 - }
40 -*/
41 -
42 -
43 -// Create the trigger
44 -await composio.triggers.subscribe(
45 - triggerData => {
46 - console.log('Received trigger:', triggerData);
47 - },
48 - {
49 - // triggerId: 'ti_9q19nLNykmVZ',
50 - // toolkits: ['GITHUB']
51 - // userId: "sid",
52 - // triggerSlug: ["GITHUB_COMMIT_EVENT"]
53 - authConfigId: 'ac_1234567890',
54 - }
3 +const composio = new Composio({apiKey: "your-api-key"});
4 +const userId = 'user-id-123435';
5 +
6 +// Check what configuration is required
7 +const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
8 +console.log(triggerType.config);
9 +// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
10 +
11 +// Create trigger with the required config
12 +const trigger = await composio.triggers.create(
13 + userId,
14 + 'GITHUB_COMMIT_EVENT',
15 + {
16 + triggerConfig: {
17 + owner: 'your-repo-owner',
18 + repo: 'your-repo-name'
19 + }
20 + }
21 );
56 -
57 -await composio.triggers.enable('ti_9q19nLNykmVZ');
58 -await composio.triggers.disable('ti_9q19nLNykmVZ');
59 -
22 +console.log(`Trigger created: ${trigger.triggerId}`);
\ No newline at end of file