@devries-cameron20 / composio Mirror · read-only / commits / 6ef299e6b
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, 10:45 UTC

docs: split triggers index into creating-triggers and subscribing-to-events

- Split monolithic index.mdx into two focused pages - creating-triggers: dashboard + SDK creation flow - subscribing-to-events: webhooks, SDK subscriptions, type-safe handling - Fix V3 payload format, Python verify_webhook param name, async verifyWebhook - Add connection expiry event handling, webhook subscriptions API references - Add tolerance param, log_id to V3 metadata - Update nav: triggers concept in Core Concepts, guides in Setting up Triggers - Remove icons from trigger concept cards Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 9, 2026 at 17:33 UTC 6ef299e6ba2169302eca6533c6ba2d9de4c0c1d7
5 files changed +139 -96
docs/content/docs/setting-up-triggers/creating-triggers.mdx new
+86
@@ -0,0 +1,86 @@
1 +---
2 +title: Creating triggers
3 +description: Create trigger instances via the dashboard or SDK
4 +keywords: [triggers, create trigger, trigger config]
5 +---
6 +
7 +<Callout type="info" title="Prerequisites">
8 +Before creating triggers, ensure you have:
9 +- An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor
10 +- A connected account for the user whose events you want to capture
11 +</Callout>
12 +
13 +You can create triggers using the Composio dashboard or programmatically via the SDK.
14 +
15 +## Using the dashboard
16 +
17 +Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs), select an auth config, and click "Add Trigger". Switch to the "Active Triggers" tab to find the trigger ID.
18 +
19 +<Video src="/videos/enabling-triggers.mp4" poster="/images/enabling-triggers-poster.png" caption="Creating a trigger from the dashboard" />
20 +
21 +Some triggers require additional configuration. The dashboard prompts you for any required fields during setup.
22 +
23 +<Figure
24 + src="/images/trigger-config.png"
25 + alt="Trigger configuration example"
26 + caption="Example: Gmail trigger configuration"
27 + size="sm"
28 +/>
29 +
30 +## Using the SDK
31 +
32 +Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
33 +
34 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
35 + <Tab value="Python">
36 +```python
37 +from composio import Composio
38 +
39 +composio = Composio(api_key="your-api-key")
40 +user_id = "user-id-123435"
41 +
42 +# Check what configuration is required
43 +trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
44 +print(trigger_type.config)
45 +# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
46 +
47 +# Create trigger with the required config
48 +trigger = composio.triggers.create(
49 + slug="GITHUB_COMMIT_EVENT",
50 + user_id=user_id,
51 + trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
52 +)
53 +print(f"Trigger created: {trigger.trigger_id}")
54 +```
55 + </Tab>
56 + <Tab value="TypeScript">
57 +```typescript
58 +import { Composio } from '@composio/core';
59 +
60 +const composio = new Composio({apiKey: "your-api-key"});
61 +const userId = 'user-id-123435';
62 +
63 +// Check what configuration is required
64 +const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
65 +console.log(triggerType.config);
66 +// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
67 +
68 +// Create trigger with the required config
69 +const trigger = await composio.triggers.create(
70 + userId,
71 + 'GITHUB_COMMIT_EVENT',
72 + {
73 + triggerConfig: {
74 + owner: 'your-repo-owner',
75 + repo: 'your-repo-name'
76 + }
77 + }
78 +);
79 +console.log(`Trigger created: ${trigger.triggerId}`);
80 +```
81 + </Tab>
82 +</Tabs>
83 +
84 +<Callout>
85 +The trigger instance uses the toolkit version configured during Composio initialization (defaults to `'latest'`). See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for details.
86 +</Callout>
docs/content/docs/setting-up-triggers/meta.json
+2 -1
@@ -1,7 +1,8 @@
1 {
2 "title": "Triggers",
3 "pages": [
4 - "index",
4 + "creating-triggers",
5 + "subscribing-to-events",
6 "webhook-verification",
7 "managing-triggers"
8 ]
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx renamed
+40 -88
@@ -1,93 +1,10 @@
1 ---
2 -title: Setting up triggers
3 -description: Create trigger instances and subscribe to events via webhooks or SDK
4 -keywords: [triggers, webhooks, subscribe, events, create trigger]
2 +title: Subscribing to events
3 +description: Receive trigger events via webhooks or SDK subscriptions
4 +keywords: [webhooks, subscribe, events, webhook payload, V3]
5 ---
6
7 -<Callout type="info" title="Prerequisites">
8 -Before setting up triggers, ensure you have:
9 -- An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor
10 -- A connected account for the user whose events you want to capture
11 -</Callout>
12 -
13 -## Creating a trigger
14 -
15 -You can create triggers using the Composio dashboard or programmatically via the SDK.
16 -
17 -### Using the dashboard
18 -
19 -Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs), select an auth config, and click "Add Trigger". Switch to the "Active Triggers" tab to find the trigger ID.
20 -
21 -<Video src="/videos/enabling-triggers.mp4" poster="/images/enabling-triggers-poster.png" caption="Creating a trigger from the dashboard" />
22 -
23 -Some triggers require additional configuration. The dashboard prompts you for any required fields during setup.
24 -
25 -<Figure
26 - src="/images/trigger-config.png"
27 - alt="Trigger configuration example"
28 - caption="Example: Gmail trigger configuration"
29 - size="sm"
30 -/>
31 -
32 -### Using the SDK
33 -
34 -Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
35 -
36 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
37 - <Tab value="Python">
38 -```python
39 -from composio import Composio
40 -
41 -composio = Composio(api_key="your-api-key")
42 -user_id = "user-id-123435"
43 -
44 -# Check what configuration is required
45 -trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
46 -print(trigger_type.config)
47 -# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
48 -
49 -# Create trigger with the required config
50 -trigger = composio.triggers.create(
51 - slug="GITHUB_COMMIT_EVENT",
52 - user_id=user_id,
53 - trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
54 -)
55 -print(f"Trigger created: {trigger.trigger_id}")
56 -```
57 - </Tab>
58 - <Tab value="TypeScript">
59 -```typescript
60 -import { Composio } from '@composio/core';
61 -
62 -const composio = new Composio({apiKey: "your-api-key"});
63 -const userId = 'user-id-123435';
64 -
65 -// Check what configuration is required
66 -const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
67 -console.log(triggerType.config);
68 -// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
69 -
70 -// Create trigger with the required config
71 -const trigger = await composio.triggers.create(
72 - userId,
73 - 'GITHUB_COMMIT_EVENT',
74 - {
75 - triggerConfig: {
76 - owner: 'your-repo-owner',
77 - repo: 'your-repo-name'
78 - }
79 - }
80 -);
81 -console.log(`Trigger created: ${trigger.triggerId}`);
82 -```
83 - </Tab>
84 -</Tabs>
85 -
86 -<Callout>
87 -The trigger instance uses the toolkit version configured during Composio initialization (defaults to `'latest'`). See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for details.
88 -</Callout>
89 -
90 -## Subscribing via webhooks
7 +## Webhooks
8
9 Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
10
@@ -114,6 +31,7 @@ New organizations receive V3 payloads by default. V3 uses a standardized `type`
31 "id": "msg_abc123",
32 "type": "composio.trigger.message",
33 "metadata": {
34 + "log_id": "log_abc123",
35 "trigger_slug": "GITHUB_COMMIT_EVENT",
36 "trigger_id": "ti_xyz789",
37 "connected_account_id": "ca_def456",
@@ -185,7 +103,41 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiRe
103 Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
104 </Callout>
105
188 -## Subscribing via SDK
106 +### Handling connection expiry events
107 +
108 +If you subscribe to `composio.connected_account.expired` events via the [Webhook Subscriptions API](/reference/api-reference/webhooks), Composio notifies you when an OAuth2 connection expires. The SDK provides typed schemas for these events:
109 +
110 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
111 + <Tab value="Python">
112 +```python
113 +from composio import is_connection_expired_event
114 +
115 +def handle_webhook(payload: dict):
116 + if is_connection_expired_event(payload):
117 + account_id = payload["data"]["id"]
118 + toolkit = payload["data"]["toolkit"]["slug"]
119 + print(f"Connection {account_id} expired for {toolkit}")
120 + # Prompt user to re-authenticate
121 +```
122 + </Tab>
123 + <Tab value="TypeScript">
124 +```typescript
125 +// @noErrors
126 +import { ConnectionExpiredEventSchema } from '@composio/core';
127 +// ---cut---
128 +function handleWebhook(payload: unknown) {
129 + const result = ConnectionExpiredEventSchema.safeParse(payload);
130 + if (result.success) {
131 + const { data, metadata } = result.data;
132 + console.log(`Connection ${data.id} expired for ${data.toolkit.slug}`);
133 + // Prompt user to re-authenticate
134 + }
135 +}
136 +```
137 + </Tab>
138 +</Tabs>
139 +
140 +## SDK subscriptions
141
142 For quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.
143
docs/content/docs/setting-up-triggers/webhook-verification.mdx
+4 -1
@@ -25,7 +25,7 @@ def webhook_handler():
25 result = composio.triggers.verify_webhook(
26 payload=request.get_data(as_text=True),
27 signature=request.headers.get("webhook-signature", ""),
28 - webhook_id=request.headers.get("webhook-id", ""),
28 + id=request.headers.get("webhook-id", ""),
29 timestamp=request.headers.get("webhook-timestamp", ""),
30 secret=os.getenv("COMPOSIO_WEBHOOK_SECRET", ""),
31 )
@@ -78,6 +78,8 @@ The method throws an error if verification fails. On success it returns:
78 | `payload` | `IncomingTriggerPayload` | Parsed and version-normalized event payload |
79 | `rawPayload` | `WebhookPayload` | Raw parsed payload before normalization |
80
81 +Both methods accept an optional `tolerance` parameter (default: `300` seconds) that controls how old a webhook can be before verification fails. Set to `0` to disable timestamp validation.
82 +
83 ## Manual verification
84
85 If you're not using the Composio SDK (e.g., Go, Rust, or another language), verify signatures manually.
@@ -161,6 +163,7 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
163 "id": "msg_abc123",
164 "type": "composio.trigger.message",
165 "metadata": {
166 + "log_id": "log_abc123",
167 "trigger_slug": "GITHUB_COMMIT_EVENT",
168 "trigger_id": "ti_xyz789",
169 "connected_account_id": "ca_def456",
docs/content/docs/triggers.mdx
+7 -6
@@ -15,9 +15,9 @@ There are two delivery types:
15
16 ## Working with triggers
17
18 -1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
19 -2. **Create** an active trigger scoped to a user's connected account
20 -3. **Configure** your webhook endpoint so Composio knows where to deliver events
18 +1. **Configure** your webhook endpoint so Composio knows where to deliver events
19 +2. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
20 +3. **Create** an active trigger scoped to a user's connected account
21 4. **Receive events**: Composio sends payloads to your endpoint
22 5. **Manage**: enable, disable, or delete triggers as needed
23
@@ -33,7 +33,8 @@ When you create a trigger from a type, it's scoped to a specific user and connec
33 ## Next steps
34
35 <Cards>
36 - <Card icon={<Rocket />} title="Setting up triggers" href="/docs/setting-up-triggers" description="Create triggers and subscribe to events via webhooks or SDK" />
37 - <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />
38 - <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
36 + <Card title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances via the dashboard or SDK" />
37 + <Card title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />
38 + <Card title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />
39 + <Card title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
40 </Cards>