@devries-cameron20 / composio-1 / commits / 9281e201a
Fork 0

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>