Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
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>