1
---
2
title: Creating triggers
3
-description: Inspect a trigger type and create the instance via the SDK or the dashboard
3
+description: Create trigger instances via the dashboard or SDK
4
keywords: [triggers, create trigger, trigger config]
5
---
6
14
15
You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). Some webhook triggers also need a webhook endpoint configured first — covered in [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below.
16
17
-## Using the SDK
18
-
19
-Before creating a trigger, inspect the trigger type. The response tells you what config it requires and whether you need to set up a webhook endpoint first.
20
-
21
-<Callout>
22
-When you pass a `user_id`, the SDK automatically finds the user's connected account for the relevant toolkit. If the user has multiple connected accounts for the same toolkit, it uses the most recently created one. You can also pass a `connected_account_id`/`connectedAccountId` directly if you need more control.
23
-</Callout>
24
-
25
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
26
- <Tab value="Python">
27
-```python
28
-from composio import Composio
29
-
30
-composio = Composio()
31
-user_id = "user-id-123435"
32
-
33
-# Inspect the trigger type
34
-trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
35
-print(trigger_type.config)
36
-# {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
37
-
38
-# Create trigger with the required config
39
-trigger = composio.triggers.create(
40
- slug="GITHUB_COMMIT_EVENT",
41
- user_id=user_id,
42
- trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
43
-)
44
-print(f"Trigger created: {trigger.trigger_id}")
45
-```
46
- </Tab>
47
- <Tab value="TypeScript">
48
-```typescript
49
-import { Composio } from '@composio/core';
50
-
51
-const composio = new Composio();
52
-const userId = 'user-id-123435';
53
-
54
-// Inspect the trigger type
55
-const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
56
-console.log(triggerType.config);
57
-// {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
58
-
59
-// Create trigger with the required config
60
-const trigger = await composio.triggers.create(
61
- userId,
62
- 'GITHUB_COMMIT_EVENT',
63
- {
64
- triggerConfig: {
65
- owner: 'your-repo-owner',
66
- repo: 'your-repo-name'
67
- }
68
- }
69
-);
70
-console.log(`Trigger created: ${trigger.triggerId}`);
71
-```
72
- </Tab>
73
-</Tabs>
74
-
75
-<Callout>
76
-Trigger instances default to the `'latest'` toolkit version. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
77
-</Callout>
78
-
79
-## Using the dashboard
80
-
81
-1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit
82
-2. Navigate to **Active Triggers** and click **Create Trigger**
83
-3. Select the connected account for which you want to create a trigger
84
-4. Choose a trigger type and fill in the required configuration. If the trigger requires a webhook endpoint, the dashboard prompts you to configure one before saving.
85
-5. Click **Create Trigger**
86
-
87
-<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />
88
-
17
## Configuring the webhook endpoint
18
19
Some webhook triggers require a webhook endpoint registered with the provider before they can fire. With Composio-managed OAuth, this is already done for you. You only run the steps below when you bring your own OAuth app and the trigger type's `requires_webhook_endpoint_setup` flag is `true`.
27
A single OAuth app can serve at most one Composio project: providers accept only one callback URL per OAuth app, and each ingress URL routes to a single project. In return, every project becomes its own webhook tenant — with:
28
29
- **Its own ingress rate limit and backpressure budget**
102
-- **Its own signing secret and app-level token**, scoped to this project alone. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped by a forged challenge.
30
+- **Project-scoped credentials** — the signing secret and app-level token you provide are stored against this project alone, never shared across projects. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped by a forged challenge.
31
- **Clean fan-out** — events reach only that project's trigger instances
32
- **Per-project metering**
33
103
104
### Step 3: Store the credentials returned by the schema
105
178
-`PATCH` each field returned by the schema. For Slack, that's the signing secret and (when applicable) the app-level token.
106
+`PATCH` all the fields the schema returned in a single request. For Slack, that's the signing secret and (when needed) the app-level token together:
107
108
```bash
109
curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
111
-H "Content-Type: application/json" \
112
-d '{
113
"data": {
186
- "webhook_signing_secret": "<SIGNING_SECRET>"
114
+ "webhook_signing_secret": "<SIGNING_SECRET>",
115
+ "app_token": "xapp-..."
116
}
117
}'
118
```
119
191
-For Slack, the signing secret lives at **Slack app → Basic Information → App Credentials → Signing Secret**.
120
+For Slack, the credentials come from:
121
+
122
+- **Signing secret** — Slack app → Basic Information → App Credentials → Signing Secret.
123
+- **App-level token** — Slack app → Basic Information → App-Level Tokens, with scope `authorizations:read`. Required for direct messages, private channels, and reactions; omit it if you only need public-channel events.
124
125
<Callout type="warn">
126
**Store the credentials before you switch the provider's callback URL in step 4.** If the provider posts to the URL without a secret on the endpoint, every request fails with `400`, and the provider may auto-disable the endpoint after a window of consecutive failures (Slack: ~36 hours).
127
</Callout>
128
197
-For toolkits with additional fields — Slack's `app_token`, for instance, which is required for direct messages, private channels, and reactions — `PATCH` them in the same way:
198
-
199
-```bash
200
-curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
201
- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
202
- -H "Content-Type: application/json" \
203
- -d '{
204
- "data": {
205
- "app_token": "xapp-..."
206
- }
207
- }'
208
-```
209
-
210
-Generate the Slack app-level token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.
211
-
129
### Step 4: Point the provider's app dashboard at the URL
130
131
Paste the `webhook_url` from step 2 into the provider's app dashboard:
133
- **Slack** → Event Subscriptions → Request URL
134
- **Notion** → Webhook Endpoints (in the integration's settings)
135
219
-For providers that issue a verification challenge on save (Slack `url_verification`, Notion's verification token, and so on), Composio responds automatically — no handshake code on your side. Once the provider accepts the URL, head back to [Using the SDK](#using-the-sdk) to create your trigger.
136
+For providers that issue a verification challenge on save (Slack `url_verification`, Notion's verification token, and so on), Composio responds automatically — no handshake code on your side. Once the provider accepts the URL, continue to [Using the SDK](#using-the-sdk) to create your trigger.
137
138
### Updating an endpoint
139
171
-H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
172
```
173
174
+## Using the SDK
175
+
176
+Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
177
+
178
+<Callout>
179
+When you pass a `user_id`, the SDK automatically finds the user's connected account for the relevant toolkit. If the user has multiple connected accounts for the same toolkit, it uses the most recently created one. You can also pass a `connected_account_id`/`connectedAccountId` directly if you need more control.
180
+</Callout>
181
+
182
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
183
+ <Tab value="Python">
184
+```python
185
+from composio import Composio
186
+
187
+composio = Composio()
188
+user_id = "user-id-123435"
189
+
190
+# Check what configuration is required
191
+trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
192
+print(trigger_type.config)
193
+# Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
194
+
195
+# Create trigger with the required config
196
+trigger = composio.triggers.create(
197
+ slug="GITHUB_COMMIT_EVENT",
198
+ user_id=user_id,
199
+ trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
200
+)
201
+print(f"Trigger created: {trigger.trigger_id}")
202
+```
203
+ </Tab>
204
+ <Tab value="TypeScript">
205
+```typescript
206
+import { Composio } from '@composio/core';
207
+
208
+const composio = new Composio();
209
+const userId = 'user-id-123435';
210
+
211
+// Check what configuration is required
212
+const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
213
+console.log(triggerType.config);
214
+// Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
215
+
216
+// Create trigger with the required config
217
+const trigger = await composio.triggers.create(
218
+ userId,
219
+ 'GITHUB_COMMIT_EVENT',
220
+ {
221
+ triggerConfig: {
222
+ owner: 'your-repo-owner',
223
+ repo: 'your-repo-name'
224
+ }
225
+ }
226
+);
227
+console.log(`Trigger created: ${trigger.triggerId}`);
228
+```
229
+ </Tab>
230
+</Tabs>
231
+
232
+<Callout>
233
+Trigger instances default to the `'latest'` toolkit version. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.
234
+</Callout>
235
+
236
+## Using the dashboard
237
+
238
+1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit
239
+2. Navigate to **Active Triggers** and click **Create Trigger**
240
+3. Select the connected account for which you want to create a trigger
241
+4. Choose a trigger type and fill in the required configuration
242
+5. Click **Create Trigger**
243
+
244
+<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />
245
+
246
## What to read next
247
248
<Cards>