@devries-cameron20 / composio-1 / commits / d102955d3
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: restructure triggers into concepts page + getting started guides

Rewrite the monolithic triggers page into a clean concepts overview with three new guide pages (setting up, webhook verification, managing). Move triggers to Core Concepts in nav, add SVG flow diagram, and absorb troubleshooting content into the managing triggers guide. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 9, 2026 at 14:54 UTC d102955d38eed9c0df4bafbe0b612c5b8d2006b5
10 files changed +934 -425
docs/content/docs/meta.json
+2 -1
@@ -8,16 +8,17 @@
8 "users-and-sessions",
9 "authentication",
10 "tools-and-toolkits",
11 + "triggers",
12 "---Getting Started---",
13 "configuring-sessions",
14 "authenticating-users",
15 "toolkits",
16 + "setting-up-triggers",
17 "---Guides---",
18 "white-labeling-authentication",
19 "managing-multiple-connected-accounts",
20 "using-custom-auth-configuration",
21 "---Features---",
20 - "triggers",
22 "cli",
23 "single-toolkit-mcp",
24 "---Direct Tool Execution Guides---",
docs/content/docs/setting-up-triggers/index.mdx new
+252
@@ -0,0 +1,252 @@
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]
5 +---
6 +
7 +<Callout type="info" title="Prerequisites">
8 +Before setting up triggers, ensure you have:
9 +- An [auth config](/docs/authentication) for the toolkit you want to monitor
10 +- A [connected account](/docs/authenticating-users) for the user whose events you want to capture
11 +- A [user ID](/docs/users-and-sessions) to scope the trigger
12 +</Callout>
13 +
14 +## Creating a trigger
15 +
16 +You can create triggers using the Composio dashboard or programmatically via the SDK.
17 +
18 +### Using the dashboard
19 +
20 +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.
21 +
22 +<Video src="/videos/enabling-triggers.mp4" poster="/images/enabling-triggers-poster.png" caption="Creating a trigger from the dashboard" />
23 +
24 +Some triggers require additional configuration. The dashboard prompts you for any required fields during setup.
25 +
26 +<Figure
27 + src="/images/trigger-config.png"
28 + alt="Trigger configuration example"
29 + caption="Example: Gmail trigger configuration"
30 + size="sm"
31 +/>
32 +
33 +### Using the SDK
34 +
35 +Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
36 +
37 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
38 + <Tab value="Python">
39 +```python
40 +from composio import Composio
41 +
42 +composio = Composio(api_key="your-api-key")
43 +user_id = "user-id-123435"
44 +
45 +# Check what configuration is required
46 +trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
47 +print(trigger_type.config)
48 +# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
49 +
50 +# Create trigger with the required config
51 +trigger = composio.triggers.create(
52 + slug="GITHUB_COMMIT_EVENT",
53 + user_id=user_id,
54 + trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
55 +)
56 +print(f"Trigger created: {trigger.trigger_id}")
57 +```
58 + </Tab>
59 + <Tab value="TypeScript">
60 +```typescript
61 +import { Composio } from '@composio/core';
62 +
63 +const composio = new Composio({apiKey: "your-api-key"});
64 +const userId = 'user-id-123435';
65 +
66 +// Check what configuration is required
67 +const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
68 +console.log(triggerType.config);
69 +// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
70 +
71 +// Create trigger with the required config
72 +const trigger = await composio.triggers.create(
73 + userId,
74 + 'GITHUB_COMMIT_EVENT',
75 + {
76 + triggerConfig: {
77 + owner: 'your-repo-owner',
78 + repo: 'your-repo-name'
79 + }
80 + }
81 +);
82 +console.log(`Trigger created: ${trigger.triggerId}`);
83 +```
84 + </Tab>
85 +</Tabs>
86 +
87 +<Callout>
88 +The trigger instance uses the toolkit version configured during Composio initialization (defaults to `'latest'`). See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for details.
89 +</Callout>
90 +
91 +## Subscribing via webhooks
92 +
93 +Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
94 +
95 +1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)
96 +2. Build an endpoint that accepts POST requests with JSON payloads
97 +
98 +<Callout type="info">
99 +**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
100 +</Callout>
101 +
102 +### Webhook payload (V3)
103 +
104 +New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:
105 +
106 +```json
107 +{
108 + "id": "wh_abc123",
109 + "type": "github_commit_event",
110 + "metadata": {
111 + "triggerId": "ti_xyz789",
112 + "connectedAccountId": "ca_def456",
113 + "userId": "user-id-123435",
114 + "toolkitSlug": "github"
115 + },
116 + "data": {
117 + "commit_sha": "a1b2c3d",
118 + "message": "fix: resolve null pointer",
119 + "author": "jane"
120 + },
121 + "timestamp": "2026-01-15T10:30:00Z"
122 +}
123 +```
124 +
125 +<Callout>
126 +See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
127 +</Callout>
128 +
129 +### Example handlers
130 +
131 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
132 + <Tab value="Python">
133 +```python
134 +@app.post("/webhook")
135 +async def webhook_handler(request: Request):
136 + payload = await request.json()
137 +
138 + trigger_type = payload.get("type")
139 + event_data = payload.get("data", {})
140 +
141 + if trigger_type == "github_commit_event":
142 + commit = event_data.get("message")
143 + author = event_data.get("author")
144 + print(f"New commit by {author}: {commit}")
145 +
146 + return {"status": "ok"}
147 +```
148 + </Tab>
149 + <Tab value="TypeScript">
150 +```typescript
151 +import { TriggerEvent } from '@composio/core';
152 +type NextApiRequest = { body: any };
153 +type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
154 +type GitHubCommitEventData = { commit_sha: string; message: string; author: string };
155 +// ---cut---
156 +export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
157 + const payload = req.body;
158 +
159 + if (payload.type === 'github_commit_event') {
160 + const event: TriggerEvent<GitHubCommitEventData> = {
161 + type: payload.type,
162 + timestamp: payload.timestamp,
163 + data: payload.data
164 + };
165 +
166 + console.log(`New commit by ${event.data.author}: ${event.data.message}`);
167 + }
168 +
169 + res.status(200).json({ status: 'ok' });
170 +}
171 +```
172 + </Tab>
173 +</Tabs>
174 +
175 +<Callout type="warn">
176 +Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
177 +</Callout>
178 +
179 +## Subscribing via SDK
180 +
181 +For quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.
182 +
183 +<Callout type="warn">
184 +SDK subscriptions use WebSockets and are intended for development only. Use webhooks in production.
185 +</Callout>
186 +
187 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
188 + <Tab value="Python">
189 +```python
190 +from composio import Composio
191 +
192 +composio = Composio(api_key="your_api_key_here")
193 +
194 +# Subscribe to trigger events
195 +subscription = composio.triggers.subscribe()
196 +
197 +@subscription.handle(trigger_id="your_trigger_id")
198 +def handle_event(data):
199 + print(f"Event received: {data}")
200 +
201 +subscription.wait_forever()
202 +```
203 + </Tab>
204 + <Tab value="TypeScript">
205 +```typescript
206 +import { Composio } from '@composio/core';
207 +
208 +const composio = new Composio({ apiKey: "your_api_key_here" });
209 +
210 +composio.triggers.subscribe(
211 + (data) => {
212 + console.log('Event received:', data);
213 + },
214 + { triggerId: 'your_trigger_id' }
215 +);
216 +```
217 + </Tab>
218 +</Tabs>
219 +
220 +### Subscription filters
221 +
222 +When subscribing via SDK, you can filter which events you receive. When multiple filters are specified, all must match.
223 +
224 +| Filter | Description |
225 +|--------|-------------|
226 +| `triggerId` | Specific trigger instance ID |
227 +| `toolkits` | Array of toolkit slugs (e.g., `["github", "slack"]`) |
228 +| `triggerSlug` | Trigger type slug (e.g., `GITHUB_COMMIT_EVENT`) |
229 +| `connectedAccountId` | Specific connected account |
230 +| `authConfigId` | Specific auth config |
231 +| `userId` | Specific user |
232 +
233 +## Type-safe trigger handling (TypeScript)
234 +
235 +Define payload types and use `TriggerEvent<T>` for type safety in your handlers:
236 +
237 +```typescript
238 +import { Composio, TriggerEvent } from '@composio/core';
239 +
240 +export type GitHubStarAddedEventPayload = {
241 + action: "created";
242 + repository_id: number;
243 + repository_name: string;
244 + repository_url: string;
245 + starred_at: string;
246 + starred_by: string;
247 +};
248 +
249 +function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
250 + console.log(`${event.data.repository_name} starred by ${event.data.starred_by}`);
251 +}
252 +```
docs/content/docs/setting-up-triggers/managing-triggers.mdx new
+258
@@ -0,0 +1,258 @@
1 +---
2 +title: Managing triggers
3 +description: Discover, list, enable, disable, and delete trigger instances
4 +keywords: [manage triggers, enable, disable, delete, discover, troubleshooting]
5 +---
6 +
7 +## Discovering available triggers
8 +
9 +### List trigger types
10 +
11 +Browse available trigger types for a toolkit:
12 +
13 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
14 + <Tab value="Python">
15 +```python
16 +from composio import Composio
17 +
18 +composio = Composio(api_key="your-api-key")
19 +
20 +# List trigger types for a toolkit
21 +trigger_types = composio.triggers.list(toolkit="github")
22 +for t in trigger_types:
23 + print(f"{t.slug}: {t.description}")
24 +```
25 + </Tab>
26 + <Tab value="TypeScript">
27 +```typescript
28 +import { Composio } from '@composio/core';
29 +
30 +const composio = new Composio({ apiKey: 'your-api-key' });
31 +
32 +// List trigger types for a toolkit
33 +const triggerTypes = await composio.triggers.listTypes({ toolkits: ['github'] });
34 +for (const t of triggerTypes.items) {
35 + console.log(`${t.slug}: ${t.description}`);
36 +}
37 +```
38 + </Tab>
39 +</Tabs>
40 +
41 +### Inspect a trigger type
42 +
43 +Get the configuration schema and payload structure for a specific trigger type:
44 +
45 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
46 + <Tab value="Python">
47 +```python
48 +from composio import Composio
49 +
50 +composio = Composio(api_key="your-api-key")
51 +
52 +trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
53 +print("Config schema:", trigger_type.config) # Required fields for creation
54 +print("Payload schema:", trigger_type.payload) # Shape of event data
55 +```
56 + </Tab>
57 + <Tab value="TypeScript">
58 +```typescript
59 +import { Composio } from '@composio/core';
60 +
61 +const composio = new Composio({ apiKey: 'your-api-key' });
62 +
63 +const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
64 +console.log('Config schema:', triggerType.config); // Required fields for creation
65 +console.log('Payload schema:', triggerType.payload); // Shape of event data
66 +```
67 + </Tab>
68 +</Tabs>
69 +
70 +### List all trigger slugs
71 +
72 +Get a flat list of every available trigger slug:
73 +
74 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
75 + <Tab value="Python">
76 +```python
77 +from composio import Composio
78 +
79 +composio = Composio(api_key="your-api-key")
80 +
81 +slugs = composio.triggers.list_enum()
82 +print(slugs) # ["GITHUB_COMMIT_EVENT", "GMAIL_NEW_EMAIL", ...]
83 +```
84 + </Tab>
85 + <Tab value="TypeScript">
86 +```typescript
87 +import { Composio } from '@composio/core';
88 +
89 +const composio = new Composio({ apiKey: 'your-api-key' });
90 +
91 +const slugs = await composio.triggers.listEnum();
92 +console.log(slugs); // ["GITHUB_COMMIT_EVENT", "GMAIL_NEW_EMAIL", ...]
93 +```
94 + </Tab>
95 +</Tabs>
96 +
97 +## Listing active triggers
98 +
99 +List trigger instances that have been created. Results are cursor-paginated.
100 +
101 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
102 + <Tab value="Python">
103 +```python
104 +from composio import Composio
105 +
106 +composio = Composio(api_key="your-api-key")
107 +
108 +# List active triggers with optional filters
109 +active = composio.triggers.list_active(
110 + toolkit="github",
111 + user_id="user-id-123435",
112 +)
113 +
114 +for trigger in active.triggers:
115 + print(f"{trigger.trigger_id} ({trigger.slug}) - {trigger.status}")
116 +
117 +# Paginate with cursor
118 +if active.next_cursor:
119 + next_page = composio.triggers.list_active(cursor=active.next_cursor)
120 +```
121 + </Tab>
122 + <Tab value="TypeScript">
123 +```typescript
124 +import { Composio } from '@composio/core';
125 +
126 +const composio = new Composio({ apiKey: 'your-api-key' });
127 +
128 +// List active triggers with optional filters
129 +const active = await composio.triggers.listActive({
130 + connectedAccountIds: ['ca_def456'],
131 +});
132 +
133 +for (const trigger of active.items) {
134 + console.log(`${trigger.id} (${trigger.triggerName}) - disabled: ${trigger.disabledAt !== null}`);
135 +}
136 +
137 +// Paginate with cursor
138 +if (active.nextCursor) {
139 + const nextPage = await composio.triggers.listActive({ cursor: active.nextCursor });
140 +}
141 +```
142 + </Tab>
143 +</Tabs>
144 +
145 +| Filter | Description |
146 +|--------|-------------|
147 +| `connectedAccountIds` | Array of connected account IDs |
148 +| `triggerIds` | Array of trigger instance IDs |
149 +| `triggerNames` | Array of trigger type slugs |
150 +| `authConfigIds` | Array of auth config IDs |
151 +| `showDisabled` | Include disabled triggers (default: `false`) |
152 +| `cursor` | Pagination cursor from previous response |
153 +
154 +## Enable / Disable triggers
155 +
156 +Pause a trigger temporarily without deleting it:
157 +
158 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
159 + <Tab value="Python">
160 +```python
161 +from composio import Composio
162 +
163 +composio = Composio(api_key="your-api-key")
164 +
165 +# Disable a trigger
166 +composio.triggers.disable(trigger_id="ti_abcd123")
167 +
168 +# Re-enable when needed
169 +composio.triggers.enable(trigger_id="ti_abcd123")
170 +```
171 + </Tab>
172 + <Tab value="TypeScript">
173 +```typescript
174 +import { Composio } from '@composio/core';
175 +const composio = new Composio({ apiKey: 'your-api-key' });
176 +// ---cut---
177 +// Disable a trigger
178 +await composio.triggers.disable('ti_abcd123');
179 +
180 +// Re-enable when needed
181 +await composio.triggers.enable('ti_abcd123');
182 +```
183 + </Tab>
184 +</Tabs>
185 +
186 +You can also manage triggers from the dashboard:
187 +
188 +1. Go to [Auth Configs](https://platform.composio.dev?next_page=/auth-configs)
189 +2. Select your auth config
190 +3. Navigate to "Active Triggers"
191 +4. Toggle the trigger on or off
192 +
193 +<Figure
194 + src="/images/trigger-enable-disable.png"
195 + alt="Enable/disable triggers"
196 + caption="Enable/disable triggers in dashboard"
197 + size="sm"
198 +/>
199 +
200 +## Deleting triggers
201 +
202 +Permanently remove a trigger instance:
203 +
204 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
205 + <Tab value="Python">
206 +```python
207 +from composio import Composio
208 +
209 +composio = Composio(api_key="your-api-key")
210 +
211 +composio.triggers.delete(trigger_id="ti_abcd123")
212 +```
213 + </Tab>
214 + <Tab value="TypeScript">
215 +```typescript
216 +import { Composio } from '@composio/core';
217 +const composio = new Composio({ apiKey: 'your-api-key' });
218 +// ---cut---
219 +await composio.triggers.delete('ti_abcd123');
220 +```
221 + </Tab>
222 +</Tabs>
223 +
224 +<Callout type="warn">
225 +Deleting a trigger is permanent. If you want to temporarily stop receiving events, use `disable()` instead.
226 +</Callout>
227 +
228 +## Troubleshooting
229 +
230 +### Unable to create trigger
231 +
232 +Check the error message — the connected account might not have sufficient permissions or the required OAuth scopes. Ensure the user has authenticated with the necessary scopes for the trigger.
233 +
234 +### Not receiving payloads
235 +
236 +- **Polling triggers** (e.g., Gmail): These check for new events at intervals (~1 min for Gmail). Expect small delays.
237 +- **Webhook URL**: Ensure your URL is publicly accessible and returns a `2xx` status code.
238 +- **Trigger status**: Verify the trigger is enabled, not disabled.
239 +- **Logs**: Check the [trigger logs](https://platform.composio.dev?next_page=/logs/triggers) in the dashboard for delivery attempts and errors.
240 +
241 +### Type errors with trigger payloads
242 +
243 +Use `getType()` / `get_type()` to inspect the exact payload schema for a trigger type. This shows you the fields and types you should expect.
244 +
245 +### Reporting issues
246 +
247 +When contacting support, include:
248 +
249 +- **Trigger ID** and **connected account ID** — find these under Active Triggers in the dashboard:
250 +
251 + <Figure src="/images/troubleshooting/troubleshooting-trigger-id.png" alt="Trigger ID and connected account ID in the dashboard" size="lg" />
252 +
253 +- **Error message** and **reproduction steps**
254 +
255 +### Getting help
256 +
257 +- **Email**: support@composio.dev
258 +- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
docs/content/docs/setting-up-triggers/meta.json new
+8
@@ -0,0 +1,8 @@
1 +{
2 + "title": "Triggers",
3 + "pages": [
4 + "index",
5 + "webhook-verification",
6 + "managing-triggers"
7 + ]
8 +}
docs/content/docs/setting-up-triggers/webhook-verification.mdx new
+218
@@ -0,0 +1,218 @@
1 +---
2 +title: Verifying webhooks
3 +description: Verify webhook signatures to ensure payloads are authentic
4 +keywords: [webhook, verification, signature, HMAC, security]
5 +---
6 +
7 +Composio signs every webhook request so you can verify the payload was sent by Composio and hasn't been tampered with. Always verify signatures in production.
8 +
9 +## Using verifyWebhook()
10 +
11 +The SDK provides a built-in method that handles signature verification and payload parsing. It auto-detects the webhook payload version (V1, V2, or V3) and throws an error if verification fails.
12 +
13 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
14 + <Tab value="Python">
15 +```python
16 +from composio import Composio
17 +from flask import Flask, request, jsonify
18 +
19 +app = Flask(__name__)
20 +composio = Composio(api_key="your-api-key")
21 +
22 +@app.route("/webhook", methods=["POST"])
23 +def webhook_handler():
24 + try:
25 + result = composio.triggers.verify_webhook(
26 + payload=request.get_data(as_text=True),
27 + signature=request.headers.get("webhook-signature", ""),
28 + webhook_id=request.headers.get("webhook-id", ""),
29 + timestamp=request.headers.get("webhook-timestamp", ""),
30 + secret=os.getenv("COMPOSIO_WEBHOOK_SECRET", ""),
31 + )
32 +
33 + # result.version: "V3", "V2", or "V1"
34 + # result.payload: parsed, version-normalized payload
35 + print(f"Verified {result.version} payload: {result.payload}")
36 + return jsonify({"status": "ok"})
37 + except Exception as e:
38 + return jsonify({"error": "Invalid signature"}), 401
39 +```
40 + </Tab>
41 + <Tab value="TypeScript">
42 +```typescript
43 +import { Composio } from '@composio/core';
44 +type Request = { body: string; headers: Record<string, string> };
45 +type Response = { status: (code: number) => { json: (data: any) => void; send: (data: string) => void }; json: (data: any) => void };
46 +// ---cut---
47 +const composio = new Composio({ apiKey: 'your-api-key' });
48 +
49 +function handleWebhook(req: Request, res: Response) {
50 + try {
51 + const result = composio.triggers.verifyWebhook({
52 + payload: req.body,
53 + signature: req.headers['webhook-signature'],
54 + id: req.headers['webhook-id'],
55 + timestamp: req.headers['webhook-timestamp'],
56 + secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
57 + });
58 +
59 + // result.version: "V3", "V2", or "V1"
60 + // result.payload: parsed, version-normalized payload
61 + console.log(`Verified ${result.version} payload:`, result.payload);
62 + res.status(200).json({ status: 'ok' });
63 + } catch (error) {
64 + res.status(401).json({ error: 'Invalid signature' });
65 + }
66 +}
67 +```
68 + </Tab>
69 +</Tabs>
70 +
71 +### VerifyWebhookResult
72 +
73 +The method throws an error if verification fails. On success it returns:
74 +
75 +| Field | Type | Description |
76 +|-------|------|-------------|
77 +| `version` | `"V1" \| "V2" \| "V3"` | Detected payload version |
78 +| `payload` | `IncomingTriggerPayload` | Parsed and version-normalized event payload |
79 +| `rawPayload` | `WebhookPayload` | Raw parsed payload before normalization |
80 +
81 +## Manual verification
82 +
83 +If you're not using the Composio SDK (e.g., Go, Rust, or another language), verify signatures manually.
84 +
85 +### Webhook headers
86 +
87 +Every webhook request includes these headers:
88 +
89 +| Header | Description |
90 +|--------|-------------|
91 +| `webhook-signature` | HMAC signature in format `v1,<base64_signature>` |
92 +| `webhook-id` | Unique message identifier |
93 +| `webhook-timestamp` | Unix timestamp when the webhook was sent |
94 +
95 +### Verification algorithm
96 +
97 +1. Extract the three headers from the request
98 +2. Build the signing string: `"{webhook-id}.{webhook-timestamp}.{raw_body}"`
99 +3. Compute `HMAC-SHA256(signing_string, secret)` and Base64-encode the result
100 +4. Compare with the signature after the `v1,` prefix
101 +
102 +```
103 +signing_string = "{webhook-id}.{webhook-timestamp}.{raw_body}"
104 +expected = base64( HMAC-SHA256( signing_string, secret ) )
105 +received = webhook-signature without "v1," prefix
106 +```
107 +
108 +### Example (manual)
109 +
110 +<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
111 + <Tab value="Python">
112 +```python
113 +import hmac
114 +import hashlib
115 +import base64
116 +import os
117 +
118 +def verify_webhook_signature(webhook_id: str, webhook_timestamp: str, body: str) -> bool:
119 + secret = os.getenv("COMPOSIO_WEBHOOK_SECRET", "")
120 + signing_string = f"{webhook_id}.{webhook_timestamp}.{body}"
121 + expected = base64.b64encode(
122 + hmac.new(secret.encode(), signing_string.encode(), hashlib.sha256).digest()
123 + ).decode()
124 + return expected
125 +```
126 + </Tab>
127 + <Tab value="TypeScript">
128 +```typescript
129 +import crypto from 'crypto';
130 +// ---cut---
131 +function verifyWebhookSignature(
132 + webhookId: string,
133 + webhookTimestamp: string,
134 + body: string
135 +): string {
136 + const secret = process.env.COMPOSIO_WEBHOOK_SECRET ?? '';
137 + const signingString = `${webhookId}.${webhookTimestamp}.${body}`;
138 + return crypto
139 + .createHmac('sha256', secret)
140 + .update(signingString)
141 + .digest('base64');
142 +}
143 +```
144 + </Tab>
145 +</Tabs>
146 +
147 +<Callout type="warn">
148 +Always use constant-time comparison (e.g., `hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js) when comparing signatures to prevent timing attacks.
149 +</Callout>
150 +
151 +## Webhook payload versions
152 +
153 +`verifyWebhook()` auto-detects the version. If you process payloads manually, here are the formats:
154 +
155 +### V3 (current default)
156 +
157 +New organizations created after Feb 15 2026 receive V3 payloads. Metadata is separated from event data.
158 +
159 +```json
160 +{
161 + "id": "wh_abc123",
162 + "type": "github_commit_event",
163 + "metadata": {
164 + "triggerId": "ti_xyz789",
165 + "connectedAccountId": "ca_def456",
166 + "userId": "user-id-123435",
167 + "toolkitSlug": "github"
168 + },
169 + "data": {
170 + "commit_sha": "a1b2c3d",
171 + "message": "fix: resolve null pointer",
172 + "author": "jane"
173 + },
174 + "timestamp": "2026-01-15T10:30:00Z"
175 +}
176 +```
177 +
178 +### V2 (legacy)
179 +
180 +```json
181 +{
182 + "type": "github_commit_event",
183 + "data": {
184 + "commit_sha": "a1b2c3d",
185 + "message": "fix: resolve null pointer",
186 + "author": "jane",
187 + "metadata": {
188 + "triggerId": "ti_xyz789",
189 + "connectedAccountId": "ca_def456"
190 + }
191 + },
192 + "timestamp": "2026-01-15T10:30:00Z",
193 + "log_id": "log_abc123"
194 +}
195 +```
196 +
197 +### V1 (legacy)
198 +
199 +```json
200 +{
201 + "trigger_name": "github_commit_event",
202 + "trigger_id": "ti_xyz789",
203 + "connected_account_id": "ca_def456",
204 + "payload": {
205 + "commit_sha": "a1b2c3d",
206 + "message": "fix: resolve null pointer",
207 + "author": "jane"
208 + }
209 +}
210 +```
211 +
212 +## Configuring your webhook URL and secret
213 +
214 +1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)
215 +2. Enter your publicly accessible webhook URL
216 +3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
217 +
218 +The SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.
docs/content/docs/triggers.mdx
+26 -387
@@ -1,399 +1,38 @@
1 ---
2 title: Triggers
3 -description: Send payloads to your AI agents or systems based on events in apps
4 -keywords: [webhooks, events, subscribe, callback]
3 +description: Understand how Composio delivers event data from connected apps
4 +keywords: [triggers, webhooks, events, polling, concepts]
5 ---
6
7 -When events occur in connected apps (like new Slack messages or GitHub commits), triggers automatically send the event data to your application.
7 +When events occur in apps, like a new Slack message, a GitHub commit, or an incoming email, triggers send event data to your application as structured payloads.
8
9 -Each event is delivered as a structured payload to your webhook endpoint (via webhooks or WebSockets), enabling your applications or AI agents to respond proactively.
9 +<Figure src="/images/triggers-flow.svg" alt="Triggers flow: Connected apps send events to Composio, which delivers them to your webhook endpoint via HTTP POST" caption="How triggers deliver events from apps to your application" />
10
11 -<Figure src="/images/triggers.png" alt="Triggers Overview" caption="Triggers through Composio" />
11 +There are two delivery types:
12
13 -<Callout type="info" title="Prerequisites">
14 -Before proceeding, ensure you've created an [auth config](/docs/tools-direct/authenticating-tools#creating-an-auth-config) and [established a connection](/docs/tools-direct/authenticating-tools#hosted-authentication-connect-link) to an app (e.g., Slack, GitHub). Triggers are scoped to specific users - learn about [User Management](/docs/users-and-sessions) for guidance on structuring User IDs.
15 -</Callout>
13 +- **Webhook triggers**: Apps like GitHub and Slack push events to Composio in real time. When an event fires, Composio forwards the payload to your webhook endpoint.
14 +- **Polling triggers**: For apps that don't support outgoing webhooks (e.g., Gmail), Composio polls for new data every minute. Expect small delays between the event and delivery.
15
17 -## Creating a trigger
16 +## Working with triggers
17
19 -You can create triggers using either the Composio dashboard or programmatically via the SDK.
18 +1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
19 +2. **Create** an active trigger scoped to a user's connected account
20 +3. **Receive events**: Composio delivers payloads to your webhook endpoint
21 +4. **Manage**: enable, disable, or delete triggers as needed
22
21 -### Using Dashboard
23 +<Accordions>
24 +<Accordion title="What is a trigger type?">
25 +A trigger type is a template that defines what event to listen for and what configuration is required. For example, `GITHUB_COMMIT_EVENT` requires an `owner` and `repo`. Each toolkit exposes its own set of trigger types.
26 +</Accordion>
27 +<Accordion title="What happens when you create an active trigger?">
28 +When you create a trigger from a type, it's scoped to a specific user and connected account. For example, creating a `GITHUB_COMMIT_EVENT` trigger for user `alice` on the `composio` repo produces a trigger with its own ID.
29 +</Accordion>
30 +</Accordions>
31
23 -To create triggers through the dashboard:
32 +## Next steps
33
25 -1. Navigate to the [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) page
26 -2. Select the auth config
27 -3. Click "Add Trigger" and navigate to "Active Triggers" tab to fetch the trigger ID
28 -
29 -<Video src="/videos/enabling-triggers.mp4" poster="/images/enabling-triggers-poster.png" caption="Creating a trigger from the dashboard" />
30 -
31 -Some triggers require additional configuration. The dashboard will prompt you for any required fields during setup.
32 -
33 -<Figure
34 - src="/images/trigger-config.png"
35 - alt="Trigger configuration example"
36 - caption="Example: Gmail trigger configuration"
37 - size="sm"
38 -/>
39 -
40 -### Using SDK
41 -
42 -Create triggers programmatically by providing the trigger type and any required configuration. The trigger instance will be created using the toolkit version configured during Composio initialization (defaults to `'latest'`).
43 -
44 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
45 - <Tab value="Python">
46 -```python
47 -from composio import Composio
48 -
49 -composio = Composio(api_key="your-api-key")
50 -user_id = "user-id-123435"
51 -
52 -# Check what configuration is required
53 -trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
54 -print(trigger_type.config)
55 -# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
56 -
57 -# Create trigger with the required config
58 -trigger = composio.triggers.create(
59 - slug="GITHUB_COMMIT_EVENT",
60 - user_id=user_id,
61 - trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
62 -)
63 -print(f"Trigger created: {trigger.trigger_id}")
64 -```
65 - </Tab>
66 - <Tab value="TypeScript">
67 -```typescript
68 -import { Composio } from '@composio/core';
69 -
70 -const composio = new Composio({apiKey: "your-api-key"});
71 -const userId = 'user-id-123435';
72 -
73 -// Check what configuration is required
74 -const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
75 -console.log(triggerType.config);
76 -// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
77 -
78 -// Create trigger with the required config
79 -const trigger = await composio.triggers.create(
80 - userId,
81 - 'GITHUB_COMMIT_EVENT',
82 - {
83 - triggerConfig: {
84 - owner: 'your-repo-owner',
85 - repo: 'your-repo-name'
86 - }
87 - }
88 -);
89 -console.log(`Trigger created: ${trigger.triggerId}`);
90 -```
91 - </Tab>
92 -</Tabs>
93 -
94 -<Callout>
95 -To use a specific toolkit version when creating triggers, configure `toolkitVersions` during initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more details.
96 -</Callout>
97 -
98 -## Subscribing to triggers
99 -
100 -### Webhooks
101 -
102 -The recommended way to subscribe to triggers is through webhooks. Configure your webhook URL in the [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events).
103 -
104 -Use a publicly accessible URL where Composio can send event payloads. This endpoint should be able to process incoming POST requests containing the trigger data.
105 -
106 -<Callout type="info">
107 -**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server to the internet for testing.
108 -</Callout>
109 -
110 -Webhook payloads contain:
111 -- `type`: The trigger type identifier
112 -- `data`: The actual event data
113 -- `timestamp`: When the event occurred
114 -- `log_id`: Unique identifier for this event
115 -
116 -Below are examples of webhook handlers for FastAPI and Next.js applications:
117 -
118 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
119 - <Tab value="Python">
120 -```python
121 -@app.post("/webhook")
122 -async def webhook_handler(request: Request):
123 - payload = await request.json()
124 -
125 - trigger_type = payload.get("type")
126 - event_data = payload.get("data", {})
127 -
128 - if trigger_type == "github_star_added_event":
129 - repo_name = event_data.get("repository_name")
130 - starred_by = event_data.get("starred_by")
131 - print(f"Repository {repo_name} starred by {starred_by}")
132 - # Add your business logic here
133 -
134 - return {"status": "success", "message": "Webhook processed"}
135 -```
136 - </Tab>
137 - <Tab value="TypeScript">
138 -```typescript
139 -import { TriggerEvent } from '@composio/core';
140 -type NextApiRequest = { body: any };
141 -type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
142 -type GitHubStarEventData = { repository_name: string; starred_by: string };
143 -// ---cut---
144 -export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
145 - const payload = req.body;
146 -
147 - if (payload.type === 'github_star_added_event') {
148 - const event: TriggerEvent<GitHubStarEventData> = {
149 - type: payload.type,
150 - timestamp: payload.timestamp,
151 - data: payload.data
152 - };
153 -
154 - console.log(`Repository ${event.data.repository_name} starred by ${event.data.starred_by}`);
155 - // Add your business logic here
156 - }
157 -
158 - res.status(200).json({
159 - status: 'success',
160 - message: 'Webhook processed'
161 - });
162 -}
163 -```
164 - </Tab>
165 -</Tabs>
166 -
167 -### Verifying webhook signatures
168 -
169 -Composio signs all webhook requests so you can verify they're authentic. Each webhook includes these headers:
170 -
171 -- `webhook-signature`: HMAC signature in format `v1,<base64_signature>`
172 -- `webhook-id`: Unique message identifier
173 -- `webhook-timestamp`: Unix timestamp when the webhook was sent
174 -
175 -To enable verification:
176 -
177 -1. Obtain your webhook secret from the [Composio dashboard](https://platform.composio.dev?next_page=/settings/webhook) under Project Settings → Webhook
178 -2. Set it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
179 -3. Use the verification function in your webhook handler:
180 -
181 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
182 - <Tab value="Python">
183 -```python
184 -def verify_webhook_signature(request: Request, body: bytes) -> bool:
185 - """Verify Composio webhook signature"""
186 - webhook_signature = request.headers.get("webhook-signature")
187 - webhook_id = request.headers.get("webhook-id")
188 - webhook_timestamp = request.headers.get("webhook-timestamp")
189 - webhook_secret = os.getenv("COMPOSIO_WEBHOOK_SECRET")
190 -
191 - if not all([webhook_signature, webhook_id, webhook_timestamp, webhook_secret]):
192 - raise HTTPException(status_code=400, detail="Missing required webhook headers or secret")
193 -
194 - if not webhook_signature.startswith("v1,"):
195 - raise HTTPException(status_code=401, detail="Invalid signature format")
196 -
197 - received = webhook_signature[3:]
198 - signing_string = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
199 - expected = base64.b64encode(
200 - hmac.new(webhook_secret.encode(), signing_string.encode(), hashlib.sha256).digest()
201 - ).decode()
202 -
203 - if not hmac.compare_digest(received, expected):
204 - raise HTTPException(status_code=401, detail="Invalid webhook signature")
205 -
206 - return True
207 -```
208 - </Tab>
209 - <Tab value="TypeScript">
210 -```typescript
211 -import crypto from 'crypto';
212 -type NextApiRequest = { headers: Record<string, string | undefined> };
213 -// ---cut---
214 -function verifyWebhookSignature(
215 - req: NextApiRequest,
216 - body: string
217 -): boolean {
218 - const signature = req.headers['webhook-signature'] as string | undefined;
219 - const msgId = req.headers['webhook-id'] as string | undefined;
220 - const timestamp = req.headers['webhook-timestamp'] as string | undefined;
221 - const secret = process.env.COMPOSIO_WEBHOOK_SECRET;
222 -
223 - if (!signature || !msgId || !timestamp || !secret) {
224 - throw new Error('Missing required webhook headers or secret');
225 - }
226 -
227 - if (!signature.startsWith('v1,')) {
228 - throw new Error('Invalid signature format');
229 - }
230 -
231 - const received = signature.slice(3);
232 - const signingString = `${msgId}.${timestamp}.${body}`;
233 - const expected = crypto
234 - .createHmac('sha256', secret)
235 - .update(signingString)
236 - .digest('base64');
237 -
238 - return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
239 -}
240 -```
241 - </Tab>
242 -</Tabs>
243 -
244 -The signature is calculated as:
245 -```
246 -signing_string = "{webhook-id}.{webhook-timestamp}.{raw_body}"
247 -signature = HMAC-SHA256(signing_string, secret)
248 -```
249 -
250 -### Prototyping with trigger subscriptions
251 -
252 -During development, you can subscribe to triggers directly through the SDK without setting up webhooks.
253 -
254 -You can subscribe to multiple trigger events by configuring the filters. When you specify multiple filters, ALL of them must match for the trigger to be subscribed to.
255 -
256 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
257 - <Tab value="Python">
258 -```python
259 -from composio import Composio
260 -
261 -# Initialize Composio client
262 -composio = Composio(api_key="your_api_key_here")
263 -
264 -# Subscribe to trigger events
265 -subscription = composio.triggers.subscribe()
266 -
267 -# Define event handler
268 -@subscription.handle(trigger_id="your_trigger_id")
269 -def handle_github_commit(data):
270 - print(f"New commit detected: {data}")
271 - # Add your custom logic here
272 -
273 -# listen for events on the trigger
274 -subscription.wait_forever()
275 -# Note: For production use, set up webhooks instead
276 -```
277 - </Tab>
278 - <Tab value="TypeScript">
279 -```typescript
280 -import { Composio } from '@composio/core';
281 -
282 -// Initialize Composio client
283 -const composio = new Composio({ apiKey: "your_api_key_here" });
284 -
285 -// Subscribe to trigger events
286 -composio.triggers.subscribe(
287 - (data) => {
288 - console.log(`New commit detected:`, data);
289 - // Add your custom logic here
290 - },
291 - { triggerId: 'your_trigger_id' }
292 -);
293 -
294 -// Note: For production use, set up webhooks instead
295 -```
296 - </Tab>
297 -</Tabs>
298 -
299 -## Trigger payload types
300 -
301 -To see what data you'll receive in your webhook handler, inspect the trigger's payload:
302 -
303 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
304 - <Tab value="Python">
305 -```python
306 -# Get trigger type to inspect payload structure
307 -trigger = composio.triggers.get_type(slug="GITHUB_COMMIT_EVENT")
308 -print(trigger.payload)
309 -```
310 - </Tab>
311 - <Tab value="TypeScript">
312 -```typescript
313 -import { Composio } from '@composio/core';
314 -const composio = new Composio({ apiKey: 'your_api_key' });
315 -// ---cut---
316 -// Get trigger type to inspect payload structure
317 -const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
318 -console.log(triggerType.payload);
319 -```
320 - </Tab>
321 -</Tabs>
322 -
323 -### Type-safe trigger handling (TypeScript)
324 -
325 -For better type safety and developer experience in TypeScript, you can define specific payload types and use the `TriggerEvent<T>` interface:
326 -
327 -```typescript
328 -import { Composio, TriggerEvent } from '@composio/core';
329 -
330 -// Define type-safe payload for GitHub Star Added event
331 -export type GitHubStarAddedEventPayload = {
332 - action: "created";
333 - repository_id: number;
334 - repository_name: string;
335 - repository_url: string;
336 - starred_at: string;
337 - starred_by: string;
338 -};
339 -
340 -// Type-safe trigger event handler
341 -function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
342 - console.log(`⭐ ${event.data.repository_name} starred by ${event.data.starred_by}`);
343 -}
344 -```
345 -
346 -This approach provides:
347 -
348 -- **IntelliSense support** for trigger payload fields
349 -- **Compile-time error checking** for typos and invalid field access
350 -- **Better documentation** through TypeScript types
351 -- **Improved maintainability** of trigger handling code
352 -
353 -## Managing triggers
354 -
355 -### Enable/disable triggers
356 -
357 -You can pause triggers temporarily without deleting them.
358 -
359 -<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
360 - <Tab value="Python">
361 -```python
362 -# Disable a trigger
363 -composio.triggers.disable(trigger_id="ti_abcd123")
364 -
365 -# Re-enable when needed
366 -composio.triggers.enable(trigger_id="ti_abcd123")
367 -```
368 - </Tab>
369 - <Tab value="TypeScript">
370 -```typescript
371 -import { Composio } from '@composio/core';
372 -const composio = new Composio({ apiKey: 'your_api_key' });
373 -// ---cut---
374 -// Disable a trigger
375 -await composio.triggers.disable('ti_abcd123');
376 -
377 -// Re-enable when needed
378 -await composio.triggers.enable('ti_abcd123');
379 -```
380 - </Tab>
381 -</Tabs>
382 -
383 -You can also manage triggers from the dashboard:
384 -
385 -1. Go to the [Auth Config](https://platform.composio.dev?next_page=/auth-configs) page
386 -2. Select your auth config
387 -3. Navigate to "Active Triggers"
388 -4. Disable/Enable the trigger
389 -
390 -<Figure
391 - src="/images/trigger-enable-disable.png"
392 - alt="Enable/disable triggers"
393 - caption="Enable/disable triggers in dashboard"
394 - size="sm"
395 -/>
396 -
397 -## Troubleshooting
398 -
399 -View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).
34 +<Cards>
35 + <Card icon={<Rocket />} title="Setting up triggers" href="/docs/setting-up-triggers" description="Create triggers and subscribe to events via webhooks or SDK" />
36 + <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />
37 + <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
38 +</Cards>
docs/content/docs/troubleshooting/meta.json
+1 -2
@@ -8,7 +8,6 @@
8 "dashboard",
9 "mcp",
10 "sdks",
11 - "tools",
12 - "triggers"
11 + "tools"
12 ]
13 }
docs/content/docs/troubleshooting/triggers.mdx deleted
-35
@@ -1,35 +0,0 @@
1 ----
2 -title: Triggers
3 -description: Troubleshooting trigger issues
4 ----
5 -
6 -## Unable to create trigger
7 -
8 -Check the error message - the account might not have sufficient permissions or required scopes.
9 -
10 -## Type errors with trigger payloads
11 -
12 -Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.
13 -
14 -## Not receiving trigger payloads
15 -
16 -Even if the action occurred (email received, Jira issue created, etc.), there may be delays:
17 -
18 -- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute
19 -- **Other services**: May have their own polling intervals or webhook delivery delays
20 -
21 -## Reporting trigger issues
22 -
23 -When reporting to support, provide:
24 -
25 -- **Error message**: Complete error details
26 -- **Connected account and trigger IDs**: Find these in the dashboard under Active Triggers:
27 -
28 - <Figure src="/images/troubleshooting/troubleshooting-trigger-id.png" alt="Example of trigger ID and connected account ID in the Composio dashboard" size="lg" />
29 -
30 -- **Reproduction steps**: Clear, step-by-step instructions to reproduce the issue, including key trigger configuration details (for example, the `interval`)
31 -
32 -## Getting help
33 -
34 -- **Email**: support@composio.dev
35 -- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
docs/content/docs/users-and-sessions.mdx
+3
@@ -26,6 +26,9 @@ account ID.
26 Here is a detailed guide on how to manage such connections:
27 <Card icon={<BookOpen />} title="Managing Multiple Connections" href="/docs/managing-multiple-connected-accounts" description="Handle multiple accounts per toolkit for a single user" />
28
29 +Triggers are also scoped per user — each trigger instance is linked to a specific user's connected account:
30 +<Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Event-driven payloads from connected apps" />
31 +
32
33 ## Sessions
34
docs/public/images/triggers-flow.svg new
+166
@@ -0,0 +1,166 @@
1 +<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 864 316" width="864" height="316">
2 +<style>
3 + @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;display=swap');
4 + text { font-family: 'Inter', system-ui, sans-serif; }
5 +
6 + /* Light mode (default) */
7 + svg {
8 + --bg: #faf8f6;
9 + --surface: #ffffff;
10 + --hdr: #f5f2ef;
11 + --border: #e0dbd8;
12 + --text: #171414;
13 + --text-sec: #5c5858;
14 + --text-muted: #8a8280;
15 + --accent: #ea580c;
16 + --accent-bg: #fef2ec;
17 + --accent-border: #f5cdb8;
18 + --accent-surface: #fef8f5;
19 + --muted-line: #c4bdb5;
20 + --muted-bg: #f3f1ee;
21 + --dot: rgba(0,0,0,0.04);
22 + --shadow-color: rgba(0,0,0,0.05);
23 + }
24 +
25 + @media (prefers-color-scheme: dark) {
26 + svg {
27 + --bg: #141414;
28 + --surface: #1c1c1c;
29 + --hdr: #222222;
30 + --border: #2e2e2e;
31 + --text: #ece8e4;
32 + --text-sec: #a09a94;
33 + --text-muted: #7a7470;
34 + --accent: #f97316;
35 + --accent-bg: #2a1a0e;
36 + --accent-border: #5c3516;
37 + --accent-surface: #221a12;
38 + --muted-line: #5e5954;
39 + --muted-bg: #242120;
40 + --dot: rgba(255,255,255,0.03);
41 + --shadow-color: rgba(0,0,0,0.3);
42 + }
43 + }
44 +</style>
45 +<defs>
46 + <!-- Shadows -->
47 + <filter id="sh" x="-4%" y="-8%" width="108%" height="124%">
48 + <feDropShadow dx="0" dy="1" stdDeviation="2.5" flood-color="var(--shadow-color)" flood-opacity="1" />
49 + </filter>
50 + <filter id="sh-sm" x="-4%" y="-8%" width="108%" height="124%">
51 + <feDropShadow dx="0" dy="0.5" stdDeviation="1.5" flood-color="var(--shadow-color)" flood-opacity="1" />
52 + </filter>
53 + <!-- Arrow markers -->
54 + <marker id="arr" markerWidth="8" markerHeight="5" refX="7.5" refY="2.5" orient="auto">
55 + <path d="M0,0.5 L7,2.5 L0,4.5" fill="var(--accent)" stroke="none" />
56 + </marker>
57 + <marker id="arr-m" markerWidth="8" markerHeight="5" refX="7.5" refY="2.5" orient="auto">
58 + <path d="M0,0.5 L7,2.5 L0,4.5" fill="var(--muted-line)" stroke="none" />
59 + </marker>
60 + <!-- Dot grid pattern -->
61 + <pattern id="dots" x="0" y="0" width="16" height="16" patternUnits="userSpaceOnUse">
62 + <circle cx="8" cy="8" r="0.6" fill="var(--dot)" />
63 + </pattern>
64 +</defs>
65 +
66 +<!-- Background -->
67 +<rect width="864" height="316" rx="12" fill="var(--bg)" />
68 +<rect width="864" height="316" rx="12" fill="url(#dots)" />
69 +
70 +<!-- ── Group: Connected Apps ── -->
71 +<g filter="url(#sh)">
72 + <rect x="40" y="40" width="115" height="236" rx="8" fill="var(--surface)" stroke="var(--border)" stroke-width="1" />
73 + <clipPath id="clip-apps"><rect x="40" y="40" width="115" height="30" rx="8" /></clipPath>
74 + <rect x="40" y="40" width="115" height="42" clip-path="url(#clip-apps)" fill="var(--hdr)" />
75 + <line x1="40" y1="70" x2="155" y2="70" stroke="var(--border)" stroke-width="0.5" />
76 +</g>
77 +<text x="97" y="55" text-anchor="middle" dy="0.35em" font-size="11" font-weight="600" letter-spacing="0.01em" fill="var(--text-sec)">Connected Apps</text>
78 +
79 +<!-- ── Group: Composio ── -->
80 +<g filter="url(#sh)">
81 + <rect x="312" y="40" width="186" height="236" rx="8" fill="var(--surface)" stroke="var(--border)" stroke-width="1" />
82 + <clipPath id="clip-comp"><rect x="312" y="40" width="186" height="30" rx="8" /></clipPath>
83 + <rect x="312" y="40" width="186" height="42" clip-path="url(#clip-comp)" fill="var(--hdr)" />
84 + <line x1="312" y1="70" x2="498" y2="70" stroke="var(--border)" stroke-width="0.5" />
85 +</g>
86 +<text x="405" y="55" text-anchor="middle" dy="0.35em" font-size="11" font-weight="600" letter-spacing="0.01em" fill="var(--text-sec)">Composio</text>
87 +
88 +<!-- ── Group: Your Application (aligned with other groups) ── -->
89 +<g filter="url(#sh)">
90 + <rect x="637" y="40" width="187" height="236" rx="8" fill="var(--surface)" stroke="var(--border)" stroke-width="1" />
91 + <clipPath id="clip-app"><rect x="637" y="40" width="187" height="30" rx="8" /></clipPath>
92 + <rect x="637" y="40" width="187" height="42" clip-path="url(#clip-app)" fill="var(--hdr)" />
93 + <line x1="637" y1="70" x2="824" y2="70" stroke="var(--border)" stroke-width="0.5" />
94 +</g>
95 +<text x="730" y="55" text-anchor="middle" dy="0.35em" font-size="11" font-weight="600" letter-spacing="0.01em" fill="var(--text-sec)">Your Application</text>
96 +
97 +<!-- ── Arrows: Apps → Composio (horizontal through labels, bend vertically in the gap) ── -->
98 +<polyline points="145,116 290,116 290,139 330,139" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
99 +<polyline points="145,176 290,176 290,153 330,153" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
100 +<!-- Polling: Composio polls Gmail (straight horizontal, right-to-left) -->
101 +<path d="M 365,236 H 145" fill="none" stroke="var(--muted-line)" stroke-width="1.25" stroke-dasharray="5 3" marker-end="url(#arr-m)" />
102 +
103 +<!-- ── Arrows: Composio → Your App (horizontal through labels, bend vertically in the gap) ── -->
104 +<polyline points="480,146 600,146 600,183 655,183" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
105 +<polyline points="445,236 600,236 600,199 655,199" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
106 +
107 +<!-- ── Edge labels (pill badges on horizontal sections) ── -->
108 +<rect x="181" y="103" width="78" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
109 +<text x="220" y="116" text-anchor="middle" dy="0.35em" font-size="10" font-weight="500" fill="var(--accent)">real-time</text>
110 +
111 +<rect x="181" y="163" width="78" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
112 +<text x="220" y="176" text-anchor="middle" dy="0.35em" font-size="10" font-weight="500" fill="var(--accent)">real-time</text>
113 +
114 +<rect x="176" y="223" width="88" height="26" rx="13" fill="var(--muted-bg)" stroke="var(--border)" stroke-width="0.5" />
115 +<text x="220" y="236" text-anchor="middle" dy="0.35em" font-size="10" font-weight="500" fill="var(--text-muted)">polls ~1 min</text>
116 +
117 +<rect x="511" y="133" width="76" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
118 +<text x="549" y="146" text-anchor="middle" dy="0.35em" font-size="10" font-weight="600" fill="var(--accent)">HTTP POST</text>
119 +
120 +<rect x="511" y="223" width="76" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
121 +<text x="549" y="236" text-anchor="middle" dy="0.35em" font-size="10" font-weight="600" fill="var(--accent)">HTTP POST</text>
122 +
123 +<!-- ── App nodes (with icons) ── -->
124 +<rect x="49" y="98" width="96" height="36" rx="6" fill="var(--surface)" stroke="var(--border)" stroke-width="0.75" filter="url(#sh-sm)" />
125 +<rect x="49" y="158" width="96" height="36" rx="6" fill="var(--surface)" stroke="var(--border)" stroke-width="0.75" filter="url(#sh-sm)" />
126 +<rect x="49" y="218" width="96" height="36" rx="6" fill="var(--surface)" stroke="var(--border)" stroke-width="0.75" filter="url(#sh-sm)" />
127 +
128 +<!-- GitHub icon (14x14) -->
129 +<g transform="translate(60,109) scale(0.109375)">
130 + <path fill-rule="evenodd" clip-rule="evenodd" d="M63.8093 1.30612C28.5244 1.30612 0 30.0408 0 65.5895C0 94.0055 18.2766 118.059 43.631 126.572C46.801 127.212 47.9621 125.189 47.9621 123.487C47.9621 121.997 47.8576 116.889 47.8576 111.566C30.1074 115.399 26.4111 103.903 26.4111 103.903C23.5585 96.4532 19.3319 94.5384 19.3319 94.5384C13.5223 90.6005 19.7551 90.6005 19.7551 90.6005C26.1995 91.0263 29.5811 97.199 29.5811 97.199C35.2849 106.99 44.4761 104.223 48.1737 102.52C48.7014 98.3693 50.3928 95.4958 52.1887 93.8997C38.0317 92.4095 23.1367 86.8754 23.1367 62.1832C23.1367 55.1589 25.6705 49.4119 29.6856 44.9424C29.0521 43.3463 26.833 36.7464 30.3203 27.9131C30.3203 27.9131 35.7081 26.21 47.8563 34.5117C53.0574 33.1045 58.4212 32.3887 63.8093 32.3827C69.1971 32.3827 74.6893 33.1285 79.761 34.5117C91.9105 26.21 97.2983 27.9131 97.2983 27.9131C100.786 36.7464 98.5652 43.3463 97.9318 44.9424C102.053 49.4119 104.482 55.1589 104.482 62.1832C104.482 86.8754 89.5869 92.3024 75.3241 93.8997C77.649 95.9216 79.6552 99.7525 79.6552 105.819C79.6552 114.44 79.5507 121.358 79.5507 123.486C79.5507 125.189 80.7132 127.212 83.8818 126.574C109.236 118.058 127.513 94.0055 127.513 65.5895C127.617 30.0408 98.9884 1.30612 63.8093 1.30612Z" fill="var(--text)"/>
131 +</g>
132 +<text x="79" y="116" text-anchor="start" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">GitHub</text>
133 +
134 +<!-- Slack icon (14x14) -->
135 +<g transform="translate(60,169) scale(0.109375)">
136 + <path d="M26.8925 80.886C26.8925 88.2866 20.8469 94.3323 13.4463 94.3323C6.04561 94.3323 0 88.2866 0 80.886C0 73.4853 6.04561 67.4397 13.4463 67.4397H26.8925V80.886Z" fill="#E01E5A"/>
137 + <path d="M33.6675 80.886C33.6675 73.4853 39.7131 67.4397 47.1137 67.4397C54.5144 67.4397 60.56 73.4853 60.56 80.886V114.554C60.56 121.954 54.5144 128 47.1137 128C39.7131 128 33.6675 121.954 33.6675 114.554V80.886Z" fill="#E01E5A"/>
138 + <path d="M47.1137 26.8925C39.7131 26.8925 33.6675 20.8469 33.6675 13.4463C33.6675 6.0456 39.7131 0 47.1137 0C54.5144 0 60.56 6.0456 60.56 13.4463V26.8925H47.1137Z" fill="#36C5F0"/>
139 + <path d="M47.114 33.6678C54.5147 33.6678 60.5603 39.7134 60.5603 47.114C60.5603 54.5147 54.5147 60.5603 47.114 60.5603H13.4463C6.0456 60.5603 0 54.5147 0 47.114C0 39.7134 6.0456 33.6678 13.4463 33.6678H47.114Z" fill="#36C5F0"/>
140 + <path d="M101.107 47.114C101.107 39.7134 107.153 33.6678 114.554 33.6678C121.954 33.6678 128 39.7134 128 47.114C128 54.5147 121.954 60.5603 114.554 60.5603H101.107V47.114Z" fill="#2EB67D"/>
141 + <path d="M94.3322 47.114C94.3322 54.5147 88.2866 60.5603 80.8859 60.5603C73.4853 60.5603 67.4397 54.5147 67.4397 47.114V13.4463C67.4397 6.0456 73.4853 0 80.8859 0C88.2866 0 94.3322 6.0456 94.3322 13.4463V47.114Z" fill="#2EB67D"/>
142 + <path d="M80.8859 101.107C88.2866 101.107 94.3322 107.153 94.3322 114.554C94.3322 121.954 88.2866 128 80.8859 128C73.4853 128 67.4397 121.954 67.4397 114.554V101.107H80.8859Z" fill="#ECB22E"/>
143 + <path d="M80.8859 94.3323C73.4853 94.3323 67.4397 88.2866 67.4397 80.886C67.4397 73.4853 73.4853 67.4397 80.8859 67.4397H114.554C121.954 67.4397 128 73.4853 128 80.886C128 88.2866 121.954 94.3323 114.554 94.3323H80.8859Z" fill="#ECB22E"/>
144 +</g>
145 +<text x="79" y="176" text-anchor="start" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">Slack</text>
146 +
147 +<!-- Gmail icon (14x14) -->
148 +<g transform="translate(60,229) scale(0.109375)">
149 + <path d="M8.7275 113.854H29.091V64.4L0 42.5817V105.127C0 109.949 3.9055 113.855 8.7275 113.855V113.854Z" fill="#4285F4"/>
150 + <path d="M98.909 113.854H119.273C124.095 113.854 128 109.949 128 105.127V42.5817L98.909 64.4V113.854Z" fill="#34A853"/>
151 + <path d="M98.909 26.5817V64.4L128 42.5817V30.9455C128 20.16 115.687 14 107.054 20.4727L98.909 26.5817Z" fill="#FBBC04"/>
152 + <path fill-rule="evenodd" clip-rule="evenodd" d="M29.091 64.4V26.5817L64 52.7638L98.909 26.5817V64.4L64 90.5817L29.091 64.4Z" fill="#EA4335"/>
153 + <path d="M0 30.9455V42.5817L29.091 64.4V26.5817L20.9455 20.4727C12.3125 14 0 20.16 0 30.945V30.9455Z" fill="#C5221F"/>
154 +</g>
155 +<text x="79" y="236" text-anchor="start" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">Gmail</text>
156 +
157 +<!-- Accent nodes (Webhook Receiver, Poller, Webhook Endpoint) -->
158 +<rect x="330" y="128" width="150" height="36" rx="6" fill="var(--accent-surface)" stroke="var(--accent-border)" stroke-width="0.75" filter="url(#sh-sm)" />
159 +<rect x="365" y="218" width="80" height="36" rx="6" fill="var(--accent-surface)" stroke="var(--accent-border)" stroke-width="0.75" filter="url(#sh-sm)" />
160 +<rect x="655" y="173" width="150" height="36" rx="6" fill="var(--accent-surface)" stroke="var(--accent-border)" stroke-width="0.75" filter="url(#sh-sm)" />
161 +
162 +<!-- ── Composio + App node labels ── -->
163 +<text x="405" y="146" text-anchor="middle" dy="0.35em" font-size="12.5" font-weight="600" fill="var(--text)">Webhook Receiver</text>
164 +<text x="405" y="236" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">Poller</text>
165 +<text x="730" y="191" text-anchor="middle" dy="0.35em" font-size="12.5" font-weight="600" fill="var(--text)">Webhook Endpoint</text>
166 +</svg>