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: revamp SDK subscriptions, add testing locally with ngrok, identifying trigger events
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
Sushmithamallesh committed
Feb 10, 2026 at 07:20 UTC
9281e201ab14982cc56a1a561043b87d005552c1
1 file changed
+36
-37
docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
+36
-37
@@ -153,22 +153,19 @@ New organizations receive V3 payloads by default. V3 separates event metadata fr
153
See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
154
</Callout>
155
156
-## SDK subscriptions
156
+## Testing locally
157
158
-For quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.
158
+### SDK subscriptions
159
160
-<Callout type="warn">
161
-SDK subscriptions use WebSockets and are intended for development only. Use webhooks in production.
162
-</Callout>
160
+Subscribe to trigger events directly through the SDK without setting up a webhook endpoint. Uses WebSockets under the hood.
161
162
<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
163
<Tab value="Python">
164
```python
165
from composio import Composio
166
169
-composio = Composio(api_key="your_api_key_here")
167
+composio = Composio()
168
171
-# Subscribe to trigger events
169
subscription = composio.triggers.subscribe()
170
171
@subscription.handle(trigger_id="your_trigger_id")
@@ -182,9 +179,9 @@ subscription.wait_forever()
179
```typescript
180
import { Composio } from '@composio/core';
181
185
-const composio = new Composio({ apiKey: "your_api_key_here" });
182
+const composio = new Composio();
183
187
-composio.triggers.subscribe(
184
+await composio.triggers.subscribe(
185
(data) => {
186
console.log('Event received:', data);
187
},
@@ -194,40 +191,42 @@ composio.triggers.subscribe(
191
</Tab>
192
</Tabs>
193
197
-### Subscription filters
198
-
199
-When subscribing via SDK, you can filter which events you receive. When multiple filters are specified, all must match.
194
+### Using ngrok
195
201
-| Filter | Description |
202
-|--------|-------------|
203
-| `triggerId` | Specific trigger instance ID |
204
-| `toolkits` | Array of toolkit slugs (e.g., `["github", "slack"]`) |
205
-| `triggerSlug` | Trigger type slug (e.g., `GITHUB_COMMIT_EVENT`) |
206
-| `connectedAccountId` | Specific connected account |
207
-| `authConfigId` | Specific auth config |
208
-| `userId` | Specific user |
196
+To test the full webhook flow locally, use [ngrok](https://ngrok.com) to expose your local server:
197
210
-## Type-safe trigger handling (TypeScript)
198
+```bash
199
+ngrok http 8000
200
+```
201
212
-Define payload types and use `TriggerEvent<T>` for type safety in your handlers:
202
+Then use the ngrok URL as your webhook endpoint:
203
214
-```typescript
215
-import { Composio, TriggerEvent } from '@composio/core';
216
-
217
-export type GitHubStarAddedEventPayload = {
218
- action: "created";
219
- repository_id: number;
220
- repository_name: string;
221
- repository_url: string;
222
- starred_at: string;
223
- starred_by: string;
224
-};
225
-
226
-function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
227
- console.log(`${event.data.repository_name} starred by ${event.data.starred_by}`);
228
-}
204
+```bash
205
+curl -X POST https://backend.composio.dev/api/v3/webhook_subscriptions \
206
+ -H "X-API-KEY: <your-composio-api-key>" \
207
+ -H "Content-Type: application/json" \
208
+ -d '{
209
+ "webhook_url": "https://your-ngrok-url.ngrok-free.app/webhook",
210
+ "enabled_events": ["composio.trigger.message"]
211
+ }'
212
```
213
214
+Events will now be forwarded to your local server at `http://localhost:8000/webhook`.
215
+
216
+## Identifying trigger events
217
+
218
+Every webhook event includes a `metadata` object that tells you exactly where it came from:
219
+
220
+| Field | What it tells you |
221
+|-------|-------------------|
222
+| `metadata.trigger_id` | Which trigger instance fired this event |
223
+| `metadata.trigger_slug` | The type of trigger (e.g., `GITHUB_COMMIT_EVENT`) |
224
+| `metadata.connected_account_id` | Which connected account it belongs to |
225
+| `metadata.user_id` | Which user it's for |
226
+| `metadata.auth_config_id` | Which auth config was used |
227
+
228
+Use `trigger_id` to match events to a specific trigger instance, or `trigger_slug` to handle all events of a certain type. These fields can also be passed as filters when using [SDK subscriptions](#sdk-subscriptions).
229
+
230
<Cards>
231
<Card title="Troubleshooting triggers" href="/docs/troubleshooting/triggers" description="Not receiving events? Check common trigger issues and how to fix them" />
232
</Cards>