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
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",
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