1
---
2
title: Creating triggers
3
-description: Configure the webhook endpoint when needed, then create trigger instances via the dashboard or SDK
3
+description: Inspect a trigger type, create the instance, and configure the webhook endpoint when required
4
keywords: [triggers, create trigger, trigger config, webhook endpoint, signing secret]
5
---
6
7
Create a trigger to start receiving events. A trigger watches for a specific event (e.g., `GITHUB_COMMIT_EVENT`) on a specific user's connected account. For an overview of how triggers work, see [Triggers](/docs/triggers).
8
9
<Callout type="info" title="Prerequisites">
10
-Before creating triggers, ensure you have:
10
- An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor
11
- A connected account for the user whose events you want to capture
13
-- For toolkits where you need to register the webhook endpoint yourself (today: Slack and Notion, when you bring your own OAuth app), the [webhook endpoint configured](#configuring-the-webhook-endpoint) before you create any triggers — see the section below to check whether yours applies.
12
</Callout>
13
16
-## Configuring the webhook endpoint
14
+You can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). If the trigger type's `requires_webhook_endpoint` flag is true and you haven't configured an endpoint yet, the create call returns a `400` — follow [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) and retry.
15
+
16
+## Using the SDK
17
+
18
+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.
19
+
20
+<Callout>
21
+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.
22
+</Callout>
23
+
24
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
25
+ <Tab value="Python">
26
+```python
27
+from composio import Composio
28
+
29
+composio = Composio()
30
+user_id = "user-id-123435"
31
+
32
+# Inspect the trigger type
33
+trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
34
+print(trigger_type.config)
35
+# {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
36
+print(trigger_type.requires_webhook_endpoint)
37
+# False → create the trigger normally
38
+# True → see "Configuring the webhook endpoint" below first
39
+
40
+# Create trigger with the required config
41
+trigger = composio.triggers.create(
42
+ slug="GITHUB_COMMIT_EVENT",
43
+ user_id=user_id,
44
+ trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
45
+)
46
+print(f"Trigger created: {trigger.trigger_id}")
47
+```
48
+ </Tab>
49
+ <Tab value="TypeScript">
50
+```typescript
51
+import { Composio } from '@composio/core';
52
+
53
+const composio = new Composio();
54
+const userId = 'user-id-123435';
55
+
56
+// Inspect the trigger type
57
+const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
58
+console.log(triggerType.config);
59
+// {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
60
+console.log(triggerType.requiresWebhookEndpoint);
61
+// false → create the trigger normally
62
+// true → see "Configuring the webhook endpoint" below first
63
18
-For a webhook trigger to fire, the provider has to know where to post events. For most toolkits, Composio handles this for you — you don't see or set up anything. For a small set of toolkits (today: **Slack** and **Notion**, with more arriving on the same flow), you set up a `webhook_endpoint` once per OAuth app: paste the provider's signing secret onto it, take the URL Composio returns, and paste that URL into the provider's app dashboard.
64
+// Create trigger with the required config
65
+const trigger = await composio.triggers.create(
66
+ userId,
67
+ 'GITHUB_COMMIT_EVENT',
68
+ {
69
+ triggerConfig: {
70
+ owner: 'your-repo-owner',
71
+ repo: 'your-repo-name'
72
+ }
73
+ }
74
+);
75
+console.log(`Trigger created: ${trigger.triggerId}`);
76
+```
77
+ </Tab>
78
+</Tabs>
79
80
<Callout>
21
-**You only do this if you bring your own OAuth app.** With Composio-managed OAuth apps, the webhook endpoint is already provisioned and you can skip ahead to [Using the SDK](#using-the-sdk).
81
+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.
82
</Callout>
83
24
-### Step 1: Discover whether you need to configure anything
84
+## Using the dashboard
85
+
86
+1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit
87
+2. Navigate to **Active Triggers** and click **Create Trigger**
88
+3. Select the connected account for which you want to create a trigger
89
+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.
90
+5. Click **Create Trigger**
91
+
92
+<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />
93
+
94
+## Configuring the webhook endpoint
95
+
96
+Skip this section unless you already know you need it — the trigger type's `requires_webhook_endpoint` flag was true, or the create call returned a `400` saying a webhook endpoint must be configured.
97
+
98
+A `webhook_endpoint` is a project-scoped resource that owns the ingress URL the provider posts to and the signing secret used to verify each request. Endpoints are keyed by `(toolkit_slug, project_id, client_id)`, so each OAuth app gets its own URL:
99
+
100
+```
101
+https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
102
+```
103
+
104
+<Callout type="warn">
105
+**A webhook endpoint ties one OAuth app to exactly one project.** If you currently share an OAuth app across multiple Composio projects, either consolidate to one project or register separate OAuth apps per project before creating an endpoint — the provider dashboard accepts only one callback URL per OAuth app.
106
+</Callout>
107
+
108
+The walkthrough below uses Slack as the example. Substitute the toolkit slug for any other toolkit on the same flow — the API surface is identical.
109
+
110
+### Step 1: Discover what credentials the endpoint needs
111
26
-Call the schema endpoint for your toolkit. The response is the source of truth.
112
+Call the schema endpoint for the toolkit. The `setup_fields` in the response tell you exactly what to collect from the provider's app dashboard.
113
114
```bash
29
-curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug={toolkit_slug}" \
115
+curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=slack" \
116
-H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
117
```
118
33
-- **Empty / no `setup_fields`** → Composio handles the endpoint for you (e.g. Asana). Skip the rest of this section and go to [Using the SDK](#using-the-sdk).
34
-- **One or more `setup_fields`** → You configure the endpoint yourself. The fields tell you exactly what to collect from the provider's app dashboard.
35
-
36
-Sample response for Slack:
119
+Sample response:
120
121
```json
122
{
165
166
Hold on to two values from the response: `id` (used as `<ENDPOINT_ID>` below) and `webhook_url` (you'll paste this into the provider's app dashboard in step 4). The call is **idempotent per `(toolkit_slug, client_id)` within a project** — calling it again with the same pair returns the existing endpoint without rotating the URL or wiping the secret.
167
85
-<Callout type="warn">
86
-**A `webhook_endpoint` ties one OAuth app to exactly one project.** If you currently share an OAuth app across multiple Composio projects, either consolidate to one project or register separate OAuth apps per project before creating an endpoint — the provider dashboard accepts only one callback URL per OAuth app.
87
-</Callout>
88
-
168
### Step 3: Store the credentials returned by the schema
169
91
-`PATCH` each field returned by the schema endpoint. For Slack, that's the signing secret and (when applicable) the app-level token.
170
+`PATCH` each field returned by the schema. For Slack, that's the signing secret and (when applicable) the app-level token.
171
172
```bash
173
curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
201
202
Generate the Slack app-level token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.
203
125
-<Callout>
126
-The schema response is the source of truth for which fields each toolkit needs. Always read `setup_fields` (step 1) for the toolkit you're configuring rather than assuming the Slack shape.
127
-</Callout>
128
-
204
### Step 4: Point the provider's app dashboard at the URL
205
206
Paste the `webhook_url` from step 2 into the provider's app dashboard:
217
-H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
218
```
219
145
-A populated `verified_at` timestamp on the response means the provider has completed the handshake. You can now create trigger instances on this OAuth app.
220
+A populated `verified_at` timestamp on the response means the provider has completed the handshake. You can now retry the trigger creation call from [Using the SDK](#using-the-sdk).
221
222
### Updating an endpoint
223
239
-d '{ "data": { "webhook_signing_secret": "<NEW_SECRET>", "app_token": "<NEW_APP_TOKEN>" } }'
240
```
241
167
-The `webhook_url` itself is immutable for the lifetime of the endpoint — rotating the signing secret on the provider side is a `PATCH` on the existing endpoint, not a new one.
242
+The `webhook_url` is immutable for the lifetime of the endpoint — rotating the signing secret on the provider side is a `PATCH` on the existing endpoint, not a new one.
243
169
-To list every endpoint in the current project (useful when operating across many OAuth apps):
244
+To list every endpoint in the current project:
245
246
```bash
247
curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
248
-H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
249
```
250
176
-## Using the SDK
177
-
178
-Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
179
-
180
-<Callout>
181
-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.
182
-</Callout>
183
-
184
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
185
- <Tab value="Python">
186
-```python
187
-from composio import Composio
188
-
189
-composio = Composio()
190
-user_id = "user-id-123435"
191
-
192
-# Check what configuration is required
193
-trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
194
-print(trigger_type.config)
195
-# Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
196
-
197
-# Create trigger with the required config
198
-trigger = composio.triggers.create(
199
- slug="GITHUB_COMMIT_EVENT",
200
- user_id=user_id,
201
- trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
202
-)
203
-print(f"Trigger created: {trigger.trigger_id}")
204
-```
205
- </Tab>
206
- <Tab value="TypeScript">
207
-```typescript
208
-import { Composio } from '@composio/core';
209
-
210
-const composio = new Composio();
211
-const userId = 'user-id-123435';
212
-
213
-// Check what configuration is required
214
-const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
215
-console.log(triggerType.config);
216
-// Returns: {"properties": {"owner": {...}, "repo": {...}}, "required": ["owner", "repo"]}
217
-
218
-// Create trigger with the required config
219
-const trigger = await composio.triggers.create(
220
- userId,
221
- 'GITHUB_COMMIT_EVENT',
222
- {
223
- triggerConfig: {
224
- owner: 'your-repo-owner',
225
- repo: 'your-repo-name'
226
- }
227
- }
228
-);
229
-console.log(`Trigger created: ${trigger.triggerId}`);
230
-```
231
- </Tab>
232
-</Tabs>
233
-
234
-<Callout>
235
-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.
236
-</Callout>
237
-
238
-## Using the dashboard
239
-
240
-1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit
241
-2. Navigate to **Active Triggers** and click **Create Trigger**
242
-3. Select the connected account for which you want to create a trigger
243
-4. Choose a trigger type and fill in the required configuration
244
-5. Click **Create Trigger**
245
-
246
-<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />
247
-
251
## What to read next
252
253
<Cards>