Skip to content

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

Sushmithamalleshd102955d38ee
diff --git a/docs/content/docs/meta.json b/docs/content/docs/meta.json
index b2f242971..f1f56f093 100644
--- a/docs/content/docs/meta.json
+++ b/docs/content/docs/meta.json
@@ -8,16 +8,17 @@
"users-and-sessions",
"authentication",
"tools-and-toolkits",
+ "triggers",
"---Getting Started---",
"configuring-sessions",
"authenticating-users",
"toolkits",
+ "setting-up-triggers",
"---Guides---",
"white-labeling-authentication",
"managing-multiple-connected-accounts",
"using-custom-auth-configuration",
"---Features---",
- "triggers",
"cli",
"single-toolkit-mcp",
"---Direct Tool Execution Guides---",
diff --git a/docs/content/docs/setting-up-triggers/index.mdx b/docs/content/docs/setting-up-triggers/index.mdx
new file mode 100644
index 000000000..a8c79e1ff
--- /dev/null
+++ b/docs/content/docs/setting-up-triggers/index.mdx
@@ -0,0 +1,252 @@
+---
+title: Setting up triggers
+description: Create trigger instances and subscribe to events via webhooks or SDK
+keywords: [triggers, webhooks, subscribe, events, create trigger]
+---
+
+<Callout type="info" title="Prerequisites">
+Before setting up triggers, ensure you have:
+- An [auth config](/docs/authentication) for the toolkit you want to monitor
+- A [connected account](/docs/authenticating-users) for the user whose events you want to capture
+- A [user ID](/docs/users-and-sessions) to scope the trigger
+</Callout>
+
+## Creating a trigger
+
+You can create triggers using the Composio dashboard or programmatically via the SDK.
+
+### Using the dashboard
+
+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.
+
+<Video src="/videos/enabling-triggers.mp4" poster="/images/enabling-triggers-poster.png" caption="Creating a trigger from the dashboard" />
+
+Some triggers require additional configuration. The dashboard prompts you for any required fields during setup.
+
+<Figure
+ src="/images/trigger-config.png"
+ alt="Trigger configuration example"
+ caption="Example: Gmail trigger configuration"
+ size="sm"
+/>
+
+### Using the SDK
+
+Before creating a trigger, inspect the trigger type to see what configuration it requires. Then create the trigger with the required config.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+user_id = "user-id-123435"
+
+# Check what configuration is required
+trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
+print(trigger_type.config)
+# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
+
+# Create trigger with the required config
+trigger = composio.triggers.create(
+ slug="GITHUB_COMMIT_EVENT",
+ user_id=user_id,
+ trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
+)
+print(f"Trigger created: {trigger.trigger_id}")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({apiKey: "your-api-key"});
+const userId = 'user-id-123435';
+
+// Check what configuration is required
+const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
+console.log(triggerType.config);
+// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
+
+// Create trigger with the required config
+const trigger = await composio.triggers.create(
+ userId,
+ 'GITHUB_COMMIT_EVENT',
+ {
+ triggerConfig: {
+ owner: 'your-repo-owner',
+ repo: 'your-repo-name'
+ }
+ }
+);
+console.log(`Trigger created: ${trigger.triggerId}`);
+```
+ </Tab>
+</Tabs>
+
+<Callout>
+The trigger instance uses the toolkit version configured during Composio initialization (defaults to `'latest'`). See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for details.
+</Callout>
+
+## Subscribing via webhooks
+
+Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
+
+1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)
+2. Build an endpoint that accepts POST requests with JSON payloads
+
+<Callout type="info">
+**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
+</Callout>
+
+### Webhook payload (V3)
+
+New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:
+
+```json
+{
+ "id": "wh_abc123",
+ "type": "github_commit_event",
+ "metadata": {
+ "triggerId": "ti_xyz789",
+ "connectedAccountId": "ca_def456",
+ "userId": "user-id-123435",
+ "toolkitSlug": "github"
+ },
+ "data": {
+ "commit_sha": "a1b2c3d",
+ "message": "fix: resolve null pointer",
+ "author": "jane"
+ },
+ "timestamp": "2026-01-15T10:30:00Z"
+}
+```
+
+<Callout>
+See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#webhook-payload-versions) for V2 and V1 formats.
+</Callout>
+
+### Example handlers
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
[email protected]("/webhook")
+async def webhook_handler(request: Request):
+ payload = await request.json()
+
+ trigger_type = payload.get("type")
+ event_data = payload.get("data", {})
+
+ if trigger_type == "github_commit_event":
+ commit = event_data.get("message")
+ author = event_data.get("author")
+ print(f"New commit by {author}: {commit}")
+
+ return {"status": "ok"}
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { TriggerEvent } from '@composio/core';
+type NextApiRequest = { body: any };
+type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
+type GitHubCommitEventData = { commit_sha: string; message: string; author: string };
+// ---cut---
+export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
+ const payload = req.body;
+
+ if (payload.type === 'github_commit_event') {
+ const event: TriggerEvent<GitHubCommitEventData> = {
+ type: payload.type,
+ timestamp: payload.timestamp,
+ data: payload.data
+ };
+
+ console.log(`New commit by ${event.data.author}: ${event.data.message}`);
+ }
+
+ res.status(200).json({ status: 'ok' });
+}
+```
+ </Tab>
+</Tabs>
+
+<Callout type="warn">
+Always [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.
+</Callout>
+
+## Subscribing via SDK
+
+For quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.
+
+<Callout type="warn">
+SDK subscriptions use WebSockets and are intended for development only. Use webhooks in production.
+</Callout>
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your_api_key_here")
+
+# Subscribe to trigger events
+subscription = composio.triggers.subscribe()
+
[email protected](trigger_id="your_trigger_id")
+def handle_event(data):
+ print(f"Event received: {data}")
+
+subscription.wait_forever()
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: "your_api_key_here" });
+
+composio.triggers.subscribe(
+ (data) => {
+ console.log('Event received:', data);
+ },
+ { triggerId: 'your_trigger_id' }
+);
+```
+ </Tab>
+</Tabs>
+
+### Subscription filters
+
+When subscribing via SDK, you can filter which events you receive. When multiple filters are specified, all must match.
+
+| Filter | Description |
+|--------|-------------|
+| `triggerId` | Specific trigger instance ID |
+| `toolkits` | Array of toolkit slugs (e.g., `["github", "slack"]`) |
+| `triggerSlug` | Trigger type slug (e.g., `GITHUB_COMMIT_EVENT`) |
+| `connectedAccountId` | Specific connected account |
+| `authConfigId` | Specific auth config |
+| `userId` | Specific user |
+
+## Type-safe trigger handling (TypeScript)
+
+Define payload types and use `TriggerEvent<T>` for type safety in your handlers:
+
+```typescript
+import { Composio, TriggerEvent } from '@composio/core';
+
+export type GitHubStarAddedEventPayload = {
+ action: "created";
+ repository_id: number;
+ repository_name: string;
+ repository_url: string;
+ starred_at: string;
+ starred_by: string;
+};
+
+function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
+ console.log(`${event.data.repository_name} starred by ${event.data.starred_by}`);
+}
+```
diff --git a/docs/content/docs/setting-up-triggers/managing-triggers.mdx b/docs/content/docs/setting-up-triggers/managing-triggers.mdx
new file mode 100644
index 000000000..ed1d4e296
--- /dev/null
+++ b/docs/content/docs/setting-up-triggers/managing-triggers.mdx
@@ -0,0 +1,258 @@
+---
+title: Managing triggers
+description: Discover, list, enable, disable, and delete trigger instances
+keywords: [manage triggers, enable, disable, delete, discover, troubleshooting]
+---
+
+## Discovering available triggers
+
+### List trigger types
+
+Browse available trigger types for a toolkit:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+
+# List trigger types for a toolkit
+trigger_types = composio.triggers.list(toolkit="github")
+for t in trigger_types:
+ print(f"{t.slug}: {t.description}")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your-api-key' });
+
+// List trigger types for a toolkit
+const triggerTypes = await composio.triggers.listTypes({ toolkits: ['github'] });
+for (const t of triggerTypes.items) {
+ console.log(`${t.slug}: ${t.description}`);
+}
+```
+ </Tab>
+</Tabs>
+
+### Inspect a trigger type
+
+Get the configuration schema and payload structure for a specific trigger type:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+
+trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
+print("Config schema:", trigger_type.config) # Required fields for creation
+print("Payload schema:", trigger_type.payload) # Shape of event data
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your-api-key' });
+
+const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
+console.log('Config schema:', triggerType.config); // Required fields for creation
+console.log('Payload schema:', triggerType.payload); // Shape of event data
+```
+ </Tab>
+</Tabs>
+
+### List all trigger slugs
+
+Get a flat list of every available trigger slug:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+
+slugs = composio.triggers.list_enum()
+print(slugs) # ["GITHUB_COMMIT_EVENT", "GMAIL_NEW_EMAIL", ...]
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your-api-key' });
+
+const slugs = await composio.triggers.listEnum();
+console.log(slugs); // ["GITHUB_COMMIT_EVENT", "GMAIL_NEW_EMAIL", ...]
+```
+ </Tab>
+</Tabs>
+
+## Listing active triggers
+
+List trigger instances that have been created. Results are cursor-paginated.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+
+# List active triggers with optional filters
+active = composio.triggers.list_active(
+ toolkit="github",
+ user_id="user-id-123435",
+)
+
+for trigger in active.triggers:
+ print(f"{trigger.trigger_id} ({trigger.slug}) - {trigger.status}")
+
+# Paginate with cursor
+if active.next_cursor:
+ next_page = composio.triggers.list_active(cursor=active.next_cursor)
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+
+const composio = new Composio({ apiKey: 'your-api-key' });
+
+// List active triggers with optional filters
+const active = await composio.triggers.listActive({
+ connectedAccountIds: ['ca_def456'],
+});
+
+for (const trigger of active.items) {
+ console.log(`${trigger.id} (${trigger.triggerName}) - disabled: ${trigger.disabledAt !== null}`);
+}
+
+// Paginate with cursor
+if (active.nextCursor) {
+ const nextPage = await composio.triggers.listActive({ cursor: active.nextCursor });
+}
+```
+ </Tab>
+</Tabs>
+
+| Filter | Description |
+|--------|-------------|
+| `connectedAccountIds` | Array of connected account IDs |
+| `triggerIds` | Array of trigger instance IDs |
+| `triggerNames` | Array of trigger type slugs |
+| `authConfigIds` | Array of auth config IDs |
+| `showDisabled` | Include disabled triggers (default: `false`) |
+| `cursor` | Pagination cursor from previous response |
+
+## Enable / Disable triggers
+
+Pause a trigger temporarily without deleting it:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+
+# Disable a trigger
+composio.triggers.disable(trigger_id="ti_abcd123")
+
+# Re-enable when needed
+composio.triggers.enable(trigger_id="ti_abcd123")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your-api-key' });
+// ---cut---
+// Disable a trigger
+await composio.triggers.disable('ti_abcd123');
+
+// Re-enable when needed
+await composio.triggers.enable('ti_abcd123');
+```
+ </Tab>
+</Tabs>
+
+You can also manage triggers from the dashboard:
+
+1. Go to [Auth Configs](https://platform.composio.dev?next_page=/auth-configs)
+2. Select your auth config
+3. Navigate to "Active Triggers"
+4. Toggle the trigger on or off
+
+<Figure
+ src="/images/trigger-enable-disable.png"
+ alt="Enable/disable triggers"
+ caption="Enable/disable triggers in dashboard"
+ size="sm"
+/>
+
+## Deleting triggers
+
+Permanently remove a trigger instance:
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+
+composio = Composio(api_key="your-api-key")
+
+composio.triggers.delete(trigger_id="ti_abcd123")
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+const composio = new Composio({ apiKey: 'your-api-key' });
+// ---cut---
+await composio.triggers.delete('ti_abcd123');
+```
+ </Tab>
+</Tabs>
+
+<Callout type="warn">
+Deleting a trigger is permanent. If you want to temporarily stop receiving events, use `disable()` instead.
+</Callout>
+
+## Troubleshooting
+
+### Unable to create trigger
+
+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.
+
+### Not receiving payloads
+
+- **Polling triggers** (e.g., Gmail): These check for new events at intervals (~1 min for Gmail). Expect small delays.
+- **Webhook URL**: Ensure your URL is publicly accessible and returns a `2xx` status code.
+- **Trigger status**: Verify the trigger is enabled, not disabled.
+- **Logs**: Check the [trigger logs](https://platform.composio.dev?next_page=/logs/triggers) in the dashboard for delivery attempts and errors.
+
+### Type errors with trigger payloads
+
+Use `getType()` / `get_type()` to inspect the exact payload schema for a trigger type. This shows you the fields and types you should expect.
+
+### Reporting issues
+
+When contacting support, include:
+
+- **Trigger ID** and **connected account ID** — find these under Active Triggers in the dashboard:
+
+ <Figure src="/images/troubleshooting/troubleshooting-trigger-id.png" alt="Trigger ID and connected account ID in the dashboard" size="lg" />
+
+- **Error message** and **reproduction steps**
+
+### Getting help
+
+- **Email**: [email protected]
+- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
diff --git a/docs/content/docs/setting-up-triggers/meta.json b/docs/content/docs/setting-up-triggers/meta.json
new file mode 100644
index 000000000..799358613
--- /dev/null
+++ b/docs/content/docs/setting-up-triggers/meta.json
@@ -0,0 +1,8 @@
+{
+ "title": "Triggers",
+ "pages": [
+ "index",
+ "webhook-verification",
+ "managing-triggers"
+ ]
+}
diff --git a/docs/content/docs/setting-up-triggers/webhook-verification.mdx b/docs/content/docs/setting-up-triggers/webhook-verification.mdx
new file mode 100644
index 000000000..456e89bc8
--- /dev/null
+++ b/docs/content/docs/setting-up-triggers/webhook-verification.mdx
@@ -0,0 +1,218 @@
+---
+title: Verifying webhooks
+description: Verify webhook signatures to ensure payloads are authentic
+keywords: [webhook, verification, signature, HMAC, security]
+---
+
+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.
+
+## Using verifyWebhook()
+
+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.
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+from composio import Composio
+from flask import Flask, request, jsonify
+
+app = Flask(__name__)
+composio = Composio(api_key="your-api-key")
+
[email protected]("/webhook", methods=["POST"])
+def webhook_handler():
+ try:
+ result = composio.triggers.verify_webhook(
+ payload=request.get_data(as_text=True),
+ signature=request.headers.get("webhook-signature", ""),
+ webhook_id=request.headers.get("webhook-id", ""),
+ timestamp=request.headers.get("webhook-timestamp", ""),
+ secret=os.getenv("COMPOSIO_WEBHOOK_SECRET", ""),
+ )
+
+ # result.version: "V3", "V2", or "V1"
+ # result.payload: parsed, version-normalized payload
+ print(f"Verified {result.version} payload: {result.payload}")
+ return jsonify({"status": "ok"})
+ except Exception as e:
+ return jsonify({"error": "Invalid signature"}), 401
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import { Composio } from '@composio/core';
+type Request = { body: string; headers: Record<string, string> };
+type Response = { status: (code: number) => { json: (data: any) => void; send: (data: string) => void }; json: (data: any) => void };
+// ---cut---
+const composio = new Composio({ apiKey: 'your-api-key' });
+
+function handleWebhook(req: Request, res: Response) {
+ try {
+ const result = composio.triggers.verifyWebhook({
+ payload: req.body,
+ signature: req.headers['webhook-signature'],
+ id: req.headers['webhook-id'],
+ timestamp: req.headers['webhook-timestamp'],
+ secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
+ });
+
+ // result.version: "V3", "V2", or "V1"
+ // result.payload: parsed, version-normalized payload
+ console.log(`Verified ${result.version} payload:`, result.payload);
+ res.status(200).json({ status: 'ok' });
+ } catch (error) {
+ res.status(401).json({ error: 'Invalid signature' });
+ }
+}
+```
+ </Tab>
+</Tabs>
+
+### VerifyWebhookResult
+
+The method throws an error if verification fails. On success it returns:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `version` | `"V1" \| "V2" \| "V3"` | Detected payload version |
+| `payload` | `IncomingTriggerPayload` | Parsed and version-normalized event payload |
+| `rawPayload` | `WebhookPayload` | Raw parsed payload before normalization |
+
+## Manual verification
+
+If you're not using the Composio SDK (e.g., Go, Rust, or another language), verify signatures manually.
+
+### Webhook headers
+
+Every webhook request includes these headers:
+
+| Header | Description |
+|--------|-------------|
+| `webhook-signature` | HMAC signature in format `v1,<base64_signature>` |
+| `webhook-id` | Unique message identifier |
+| `webhook-timestamp` | Unix timestamp when the webhook was sent |
+
+### Verification algorithm
+
+1. Extract the three headers from the request
+2. Build the signing string: `"{webhook-id}.{webhook-timestamp}.{raw_body}"`
+3. Compute `HMAC-SHA256(signing_string, secret)` and Base64-encode the result
+4. Compare with the signature after the `v1,` prefix
+
+```
+signing_string = "{webhook-id}.{webhook-timestamp}.{raw_body}"
+expected = base64( HMAC-SHA256( signing_string, secret ) )
+received = webhook-signature without "v1," prefix
+```
+
+### Example (manual)
+
+<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
+ <Tab value="Python">
+```python
+import hmac
+import hashlib
+import base64
+import os
+
+def verify_webhook_signature(webhook_id: str, webhook_timestamp: str, body: str) -> bool:
+ secret = os.getenv("COMPOSIO_WEBHOOK_SECRET", "")
+ signing_string = f"{webhook_id}.{webhook_timestamp}.{body}"
+ expected = base64.b64encode(
+ hmac.new(secret.encode(), signing_string.encode(), hashlib.sha256).digest()
+ ).decode()
+ return expected
+```
+ </Tab>
+ <Tab value="TypeScript">
+```typescript
+import crypto from 'crypto';
+// ---cut---
+function verifyWebhookSignature(
+ webhookId: string,
+ webhookTimestamp: string,
+ body: string
+): string {
+ const secret = process.env.COMPOSIO_WEBHOOK_SECRET ?? '';
+ const signingString = `${webhookId}.${webhookTimestamp}.${body}`;
+ return crypto
+ .createHmac('sha256', secret)
+ .update(signingString)
+ .digest('base64');
+}
+```
+ </Tab>
+</Tabs>
+
+<Callout type="warn">
+Always use constant-time comparison (e.g., `hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js) when comparing signatures to prevent timing attacks.
+</Callout>
+
+## Webhook payload versions
+
+`verifyWebhook()` auto-detects the version. If you process payloads manually, here are the formats:
+
+### V3 (current default)
+
+New organizations created after Feb 15 2026 receive V3 payloads. Metadata is separated from event data.
+
+```json
+{
+ "id": "wh_abc123",
+ "type": "github_commit_event",
+ "metadata": {
+ "triggerId": "ti_xyz789",
+ "connectedAccountId": "ca_def456",
+ "userId": "user-id-123435",
+ "toolkitSlug": "github"
+ },
+ "data": {
+ "commit_sha": "a1b2c3d",
+ "message": "fix: resolve null pointer",
+ "author": "jane"
+ },
+ "timestamp": "2026-01-15T10:30:00Z"
+}
+```
+
+### V2 (legacy)
+
+```json
+{
+ "type": "github_commit_event",
+ "data": {
+ "commit_sha": "a1b2c3d",
+ "message": "fix: resolve null pointer",
+ "author": "jane",
+ "metadata": {
+ "triggerId": "ti_xyz789",
+ "connectedAccountId": "ca_def456"
+ }
+ },
+ "timestamp": "2026-01-15T10:30:00Z",
+ "log_id": "log_abc123"
+}
+```
+
+### V1 (legacy)
+
+```json
+{
+ "trigger_name": "github_commit_event",
+ "trigger_id": "ti_xyz789",
+ "connected_account_id": "ca_def456",
+ "payload": {
+ "commit_sha": "a1b2c3d",
+ "message": "fix: resolve null pointer",
+ "author": "jane"
+ }
+}
+```
+
+## Configuring your webhook URL and secret
+
+1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)
+2. Enter your publicly accessible webhook URL
+3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
+
+The SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.
diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdx
index cf3c64c29..16c3f5703 100644
--- a/docs/content/docs/triggers.mdx
+++ b/docs/content/docs/triggers.mdx
@@ -1,399 +1,38 @@
---
title: Triggers
-description: Send payloads to your AI agents or systems based on events in apps
-keywords: [webhooks, events, subscribe, callback]
+description: Understand how Composio delivers event data from connected apps
+keywords: [triggers, webhooks, events, polling, concepts]
---
-When events occur in connected apps (like new Slack messages or GitHub commits), triggers automatically send the event data to your application.
+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.
-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.
+<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" />
-<Figure src="/images/triggers.png" alt="Triggers Overview" caption="Triggers through Composio" />
+There are two delivery types:
-<Callout type="info" title="Prerequisites">
-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.
-</Callout>
+- **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.
+- **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.
-## Creating a trigger
+## Working with triggers
-You can create triggers using either the Composio dashboard or programmatically via the SDK.
+1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
+2. **Create** an active trigger scoped to a user's connected account
+3. **Receive events**: Composio delivers payloads to your webhook endpoint
+4. **Manage**: enable, disable, or delete triggers as needed
-### Using Dashboard
+<Accordions>
+<Accordion title="What is a trigger type?">
+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.
+</Accordion>
+<Accordion title="What happens when you create an active trigger?">
+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.
+</Accordion>
+</Accordions>
-To create triggers through the dashboard:
+## Next steps
-1. Navigate to the [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) page
-2. Select the auth config
-3. Click "Add Trigger" and navigate to "Active Triggers" tab to fetch the trigger ID
-
-<Video src="/videos/enabling-triggers.mp4" poster="/images/enabling-triggers-poster.png" caption="Creating a trigger from the dashboard" />
-
-Some triggers require additional configuration. The dashboard will prompt you for any required fields during setup.
-
-<Figure
- src="/images/trigger-config.png"
- alt="Trigger configuration example"
- caption="Example: Gmail trigger configuration"
- size="sm"
-/>
-
-### Using SDK
-
-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'`).
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
- <Tab value="Python">
-```python
-from composio import Composio
-
-composio = Composio(api_key="your-api-key")
-user_id = "user-id-123435"
-
-# Check what configuration is required
-trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")
-print(trigger_type.config)
-# Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
-
-# Create trigger with the required config
-trigger = composio.triggers.create(
- slug="GITHUB_COMMIT_EVENT",
- user_id=user_id,
- trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},
-)
-print(f"Trigger created: {trigger.trigger_id}")
-```
- </Tab>
- <Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-
-const composio = new Composio({apiKey: "your-api-key"});
-const userId = 'user-id-123435';
-
-// Check what configuration is required
-const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");
-console.log(triggerType.config);
-// Returns: {"properties": {...}, "required": ["owner", "repo"], ...}
-
-// Create trigger with the required config
-const trigger = await composio.triggers.create(
- userId,
- 'GITHUB_COMMIT_EVENT',
- {
- triggerConfig: {
- owner: 'your-repo-owner',
- repo: 'your-repo-name'
- }
- }
-);
-console.log(`Trigger created: ${trigger.triggerId}`);
-```
- </Tab>
-</Tabs>
-
-<Callout>
-To use a specific toolkit version when creating triggers, configure `toolkitVersions` during initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning) for more details.
-</Callout>
-
-## Subscribing to triggers
-
-### Webhooks
-
-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).
-
-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.
-
-<Callout type="info">
-**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server to the internet for testing.
-</Callout>
-
-Webhook payloads contain:
-- `type`: The trigger type identifier
-- `data`: The actual event data
-- `timestamp`: When the event occurred
-- `log_id`: Unique identifier for this event
-
-Below are examples of webhook handlers for FastAPI and Next.js applications:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
- <Tab value="Python">
-```python
[email protected]("/webhook")
-async def webhook_handler(request: Request):
- payload = await request.json()
-
- trigger_type = payload.get("type")
- event_data = payload.get("data", {})
-
- if trigger_type == "github_star_added_event":
- repo_name = event_data.get("repository_name")
- starred_by = event_data.get("starred_by")
- print(f"Repository {repo_name} starred by {starred_by}")
- # Add your business logic here
-
- return {"status": "success", "message": "Webhook processed"}
-```
- </Tab>
- <Tab value="TypeScript">
-```typescript
-import { TriggerEvent } from '@composio/core';
-type NextApiRequest = { body: any };
-type NextApiResponse = { status: (code: number) => { json: (data: any) => void }; json: (data: any) => void };
-type GitHubStarEventData = { repository_name: string; starred_by: string };
-// ---cut---
-export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
- const payload = req.body;
-
- if (payload.type === 'github_star_added_event') {
- const event: TriggerEvent<GitHubStarEventData> = {
- type: payload.type,
- timestamp: payload.timestamp,
- data: payload.data
- };
-
- console.log(`Repository ${event.data.repository_name} starred by ${event.data.starred_by}`);
- // Add your business logic here
- }
-
- res.status(200).json({
- status: 'success',
- message: 'Webhook processed'
- });
-}
-```
- </Tab>
-</Tabs>
-
-### Verifying webhook signatures
-
-Composio signs all webhook requests so you can verify they're authentic. Each webhook includes these headers:
-
-- `webhook-signature`: HMAC signature in format `v1,<base64_signature>`
-- `webhook-id`: Unique message identifier
-- `webhook-timestamp`: Unix timestamp when the webhook was sent
-
-To enable verification:
-
-1. Obtain your webhook secret from the [Composio dashboard](https://platform.composio.dev?next_page=/settings/webhook) under Project Settings → Webhook
-2. Set it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
-3. Use the verification function in your webhook handler:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
- <Tab value="Python">
-```python
-def verify_webhook_signature(request: Request, body: bytes) -> bool:
- """Verify Composio webhook signature"""
- webhook_signature = request.headers.get("webhook-signature")
- webhook_id = request.headers.get("webhook-id")
- webhook_timestamp = request.headers.get("webhook-timestamp")
- webhook_secret = os.getenv("COMPOSIO_WEBHOOK_SECRET")
-
- if not all([webhook_signature, webhook_id, webhook_timestamp, webhook_secret]):
- raise HTTPException(status_code=400, detail="Missing required webhook headers or secret")
-
- if not webhook_signature.startswith("v1,"):
- raise HTTPException(status_code=401, detail="Invalid signature format")
-
- received = webhook_signature[3:]
- signing_string = f"{webhook_id}.{webhook_timestamp}.{body.decode()}"
- expected = base64.b64encode(
- hmac.new(webhook_secret.encode(), signing_string.encode(), hashlib.sha256).digest()
- ).decode()
-
- if not hmac.compare_digest(received, expected):
- raise HTTPException(status_code=401, detail="Invalid webhook signature")
-
- return True
-```
- </Tab>
- <Tab value="TypeScript">
-```typescript
-import crypto from 'crypto';
-type NextApiRequest = { headers: Record<string, string | undefined> };
-// ---cut---
-function verifyWebhookSignature(
- req: NextApiRequest,
- body: string
-): boolean {
- const signature = req.headers['webhook-signature'] as string | undefined;
- const msgId = req.headers['webhook-id'] as string | undefined;
- const timestamp = req.headers['webhook-timestamp'] as string | undefined;
- const secret = process.env.COMPOSIO_WEBHOOK_SECRET;
-
- if (!signature || !msgId || !timestamp || !secret) {
- throw new Error('Missing required webhook headers or secret');
- }
-
- if (!signature.startsWith('v1,')) {
- throw new Error('Invalid signature format');
- }
-
- const received = signature.slice(3);
- const signingString = `${msgId}.${timestamp}.${body}`;
- const expected = crypto
- .createHmac('sha256', secret)
- .update(signingString)
- .digest('base64');
-
- return crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
-}
-```
- </Tab>
-</Tabs>
-
-The signature is calculated as:
-```
-signing_string = "{webhook-id}.{webhook-timestamp}.{raw_body}"
-signature = HMAC-SHA256(signing_string, secret)
-```
-
-### Prototyping with trigger subscriptions
-
-During development, you can subscribe to triggers directly through the SDK without setting up webhooks.
-
-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.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
- <Tab value="Python">
-```python
-from composio import Composio
-
-# Initialize Composio client
-composio = Composio(api_key="your_api_key_here")
-
-# Subscribe to trigger events
-subscription = composio.triggers.subscribe()
-
-# Define event handler
[email protected](trigger_id="your_trigger_id")
-def handle_github_commit(data):
- print(f"New commit detected: {data}")
- # Add your custom logic here
-
-# listen for events on the trigger
-subscription.wait_forever()
-# Note: For production use, set up webhooks instead
-```
- </Tab>
- <Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-
-// Initialize Composio client
-const composio = new Composio({ apiKey: "your_api_key_here" });
-
-// Subscribe to trigger events
-composio.triggers.subscribe(
- (data) => {
- console.log(`New commit detected:`, data);
- // Add your custom logic here
- },
- { triggerId: 'your_trigger_id' }
-);
-
-// Note: For production use, set up webhooks instead
-```
- </Tab>
-</Tabs>
-
-## Trigger payload types
-
-To see what data you'll receive in your webhook handler, inspect the trigger's payload:
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
- <Tab value="Python">
-```python
-# Get trigger type to inspect payload structure
-trigger = composio.triggers.get_type(slug="GITHUB_COMMIT_EVENT")
-print(trigger.payload)
-```
- </Tab>
- <Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-// Get trigger type to inspect payload structure
-const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');
-console.log(triggerType.payload);
-```
- </Tab>
-</Tabs>
-
-### Type-safe trigger handling (TypeScript)
-
-For better type safety and developer experience in TypeScript, you can define specific payload types and use the `TriggerEvent<T>` interface:
-
-```typescript
-import { Composio, TriggerEvent } from '@composio/core';
-
-// Define type-safe payload for GitHub Star Added event
-export type GitHubStarAddedEventPayload = {
- action: "created";
- repository_id: number;
- repository_name: string;
- repository_url: string;
- starred_at: string;
- starred_by: string;
-};
-
-// Type-safe trigger event handler
-function handleGitHubStarEvent(event: TriggerEvent<GitHubStarAddedEventPayload>) {
- console.log(`⭐ ${event.data.repository_name} starred by ${event.data.starred_by}`);
-}
-```
-
-This approach provides:
-
-- **IntelliSense support** for trigger payload fields
-- **Compile-time error checking** for typos and invalid field access
-- **Better documentation** through TypeScript types
-- **Improved maintainability** of trigger handling code
-
-## Managing triggers
-
-### Enable/disable triggers
-
-You can pause triggers temporarily without deleting them.
-
-<Tabs groupId="language" items={['Python', 'TypeScript']} persist>
- <Tab value="Python">
-```python
-# Disable a trigger
-composio.triggers.disable(trigger_id="ti_abcd123")
-
-# Re-enable when needed
-composio.triggers.enable(trigger_id="ti_abcd123")
-```
- </Tab>
- <Tab value="TypeScript">
-```typescript
-import { Composio } from '@composio/core';
-const composio = new Composio({ apiKey: 'your_api_key' });
-// ---cut---
-// Disable a trigger
-await composio.triggers.disable('ti_abcd123');
-
-// Re-enable when needed
-await composio.triggers.enable('ti_abcd123');
-```
- </Tab>
-</Tabs>
-
-You can also manage triggers from the dashboard:
-
-1. Go to the [Auth Config](https://platform.composio.dev?next_page=/auth-configs) page
-2. Select your auth config
-3. Navigate to "Active Triggers"
-4. Disable/Enable the trigger
-
-<Figure
- src="/images/trigger-enable-disable.png"
- alt="Enable/disable triggers"
- caption="Enable/disable triggers in dashboard"
- size="sm"
-/>
-
-## Troubleshooting
-
-View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).
+<Cards>
+ <Card icon={<Rocket />} title="Setting up triggers" href="/docs/setting-up-triggers" description="Create triggers and subscribe to events via webhooks or SDK" />
+ <Card icon={<ShieldCheck />} title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />
+ <Card icon={<Wrench />} title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" />
+</Cards>
diff --git a/docs/content/docs/troubleshooting/meta.json b/docs/content/docs/troubleshooting/meta.json
index ab36ebb3c..4964f71c3 100644
--- a/docs/content/docs/troubleshooting/meta.json
+++ b/docs/content/docs/troubleshooting/meta.json
@@ -8,7 +8,6 @@
"dashboard",
"mcp",
"sdks",
- "tools",
- "triggers"
+ "tools"
]
}
diff --git a/docs/content/docs/troubleshooting/triggers.mdx b/docs/content/docs/troubleshooting/triggers.mdx
deleted file mode 100644
index e5c3bc49b..000000000
--- a/docs/content/docs/troubleshooting/triggers.mdx
+++ /dev/null
@@ -1,35 +0,0 @@
----
-title: Triggers
-description: Troubleshooting trigger issues
----
-
-## Unable to create trigger
-
-Check the error message - the account might not have sufficient permissions or required scopes.
-
-## Type errors with trigger payloads
-
-Having issues with trigger payload types? Search [DeepWiki](https://deepwiki.com/ComposioHQ/composio) or use the Ask AI assistant for type definitions and examples.
-
-## Not receiving trigger payloads
-
-Even if the action occurred (email received, Jira issue created, etc.), there may be delays:
-
-- **Gmail triggers**: Uses polling with minimum 1-minute frequency - expect delays of up to a minute
-- **Other services**: May have their own polling intervals or webhook delivery delays
-
-## Reporting trigger issues
-
-When reporting to support, provide:
-
-- **Error message**: Complete error details
-- **Connected account and trigger IDs**: Find these in the dashboard under Active Triggers:
-
- <Figure src="/images/troubleshooting/troubleshooting-trigger-id.png" alt="Example of trigger ID and connected account ID in the Composio dashboard" size="lg" />
-
-- **Reproduction steps**: Clear, step-by-step instructions to reproduce the issue, including key trigger configuration details (for example, the `interval`)
-
-## Getting help
-
-- **Email**: [email protected]
-- **Discord**: [#support-form](https://discord.com/channels/1170785031560646836/1268871288156323901)
diff --git a/docs/content/docs/users-and-sessions.mdx b/docs/content/docs/users-and-sessions.mdx
index 2e04975c7..7a03d8409 100644
--- a/docs/content/docs/users-and-sessions.mdx
+++ b/docs/content/docs/users-and-sessions.mdx
@@ -26,6 +26,9 @@ account ID.
Here is a detailed guide on how to manage such connections:
<Card icon={<BookOpen />} title="Managing Multiple Connections" href="/docs/managing-multiple-connected-accounts" description="Handle multiple accounts per toolkit for a single user" />
+Triggers are also scoped per user — each trigger instance is linked to a specific user's connected account:
+<Card icon={<Zap />} title="Triggers" href="/docs/triggers" description="Event-driven payloads from connected apps" />
+
## Sessions
diff --git a/docs/public/images/triggers-flow.svg b/docs/public/images/triggers-flow.svg
new file mode 100644
index 000000000..3f3900c45
--- /dev/null
+++ b/docs/public/images/triggers-flow.svg
@@ -0,0 +1,166 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 864 316" width="864" height="316">
+<style>
+ @import url('https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&amp;display=swap');
+ text { font-family: 'Inter', system-ui, sans-serif; }
+
+ /* Light mode (default) */
+ svg {
+ --bg: #faf8f6;
+ --surface: #ffffff;
+ --hdr: #f5f2ef;
+ --border: #e0dbd8;
+ --text: #171414;
+ --text-sec: #5c5858;
+ --text-muted: #8a8280;
+ --accent: #ea580c;
+ --accent-bg: #fef2ec;
+ --accent-border: #f5cdb8;
+ --accent-surface: #fef8f5;
+ --muted-line: #c4bdb5;
+ --muted-bg: #f3f1ee;
+ --dot: rgba(0,0,0,0.04);
+ --shadow-color: rgba(0,0,0,0.05);
+ }
+
+ @media (prefers-color-scheme: dark) {
+ svg {
+ --bg: #141414;
+ --surface: #1c1c1c;
+ --hdr: #222222;
+ --border: #2e2e2e;
+ --text: #ece8e4;
+ --text-sec: #a09a94;
+ --text-muted: #7a7470;
+ --accent: #f97316;
+ --accent-bg: #2a1a0e;
+ --accent-border: #5c3516;
+ --accent-surface: #221a12;
+ --muted-line: #5e5954;
+ --muted-bg: #242120;
+ --dot: rgba(255,255,255,0.03);
+ --shadow-color: rgba(0,0,0,0.3);
+ }
+ }
+</style>
+<defs>
+ <!-- Shadows -->
+ <filter id="sh" x="-4%" y="-8%" width="108%" height="124%">
+ <feDropShadow dx="0" dy="1" stdDeviation="2.5" flood-color="var(--shadow-color)" flood-opacity="1" />
+ </filter>
+ <filter id="sh-sm" x="-4%" y="-8%" width="108%" height="124%">
+ <feDropShadow dx="0" dy="0.5" stdDeviation="1.5" flood-color="var(--shadow-color)" flood-opacity="1" />
+ </filter>
+ <!-- Arrow markers -->
+ <marker id="arr" markerWidth="8" markerHeight="5" refX="7.5" refY="2.5" orient="auto">
+ <path d="M0,0.5 L7,2.5 L0,4.5" fill="var(--accent)" stroke="none" />
+ </marker>
+ <marker id="arr-m" markerWidth="8" markerHeight="5" refX="7.5" refY="2.5" orient="auto">
+ <path d="M0,0.5 L7,2.5 L0,4.5" fill="var(--muted-line)" stroke="none" />
+ </marker>
+ <!-- Dot grid pattern -->
+ <pattern id="dots" x="0" y="0" width="16" height="16" patternUnits="userSpaceOnUse">
+ <circle cx="8" cy="8" r="0.6" fill="var(--dot)" />
+ </pattern>
+</defs>
+
+<!-- Background -->
+<rect width="864" height="316" rx="12" fill="var(--bg)" />
+<rect width="864" height="316" rx="12" fill="url(#dots)" />
+
+<!-- ── Group: Connected Apps ── -->
+<g filter="url(#sh)">
+ <rect x="40" y="40" width="115" height="236" rx="8" fill="var(--surface)" stroke="var(--border)" stroke-width="1" />
+ <clipPath id="clip-apps"><rect x="40" y="40" width="115" height="30" rx="8" /></clipPath>
+ <rect x="40" y="40" width="115" height="42" clip-path="url(#clip-apps)" fill="var(--hdr)" />
+ <line x1="40" y1="70" x2="155" y2="70" stroke="var(--border)" stroke-width="0.5" />
+</g>
+<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>
+
+<!-- ── Group: Composio ── -->
+<g filter="url(#sh)">
+ <rect x="312" y="40" width="186" height="236" rx="8" fill="var(--surface)" stroke="var(--border)" stroke-width="1" />
+ <clipPath id="clip-comp"><rect x="312" y="40" width="186" height="30" rx="8" /></clipPath>
+ <rect x="312" y="40" width="186" height="42" clip-path="url(#clip-comp)" fill="var(--hdr)" />
+ <line x1="312" y1="70" x2="498" y2="70" stroke="var(--border)" stroke-width="0.5" />
+</g>
+<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>
+
+<!-- ── Group: Your Application (aligned with other groups) ── -->
+<g filter="url(#sh)">
+ <rect x="637" y="40" width="187" height="236" rx="8" fill="var(--surface)" stroke="var(--border)" stroke-width="1" />
+ <clipPath id="clip-app"><rect x="637" y="40" width="187" height="30" rx="8" /></clipPath>
+ <rect x="637" y="40" width="187" height="42" clip-path="url(#clip-app)" fill="var(--hdr)" />
+ <line x1="637" y1="70" x2="824" y2="70" stroke="var(--border)" stroke-width="0.5" />
+</g>
+<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>
+
+<!-- ── Arrows: Apps → Composio (horizontal through labels, bend vertically in the gap) ── -->
+<polyline points="145,116 290,116 290,139 330,139" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
+<polyline points="145,176 290,176 290,153 330,153" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
+<!-- Polling: Composio polls Gmail (straight horizontal, right-to-left) -->
+<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)" />
+
+<!-- ── Arrows: Composio → Your App (horizontal through labels, bend vertically in the gap) ── -->
+<polyline points="480,146 600,146 600,183 655,183" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
+<polyline points="445,236 600,236 600,199 655,199" fill="none" stroke="var(--accent)" stroke-width="1.25" marker-end="url(#arr)" />
+
+<!-- ── Edge labels (pill badges on horizontal sections) ── -->
+<rect x="181" y="103" width="78" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
+<text x="220" y="116" text-anchor="middle" dy="0.35em" font-size="10" font-weight="500" fill="var(--accent)">real-time</text>
+
+<rect x="181" y="163" width="78" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
+<text x="220" y="176" text-anchor="middle" dy="0.35em" font-size="10" font-weight="500" fill="var(--accent)">real-time</text>
+
+<rect x="176" y="223" width="88" height="26" rx="13" fill="var(--muted-bg)" stroke="var(--border)" stroke-width="0.5" />
+<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>
+
+<rect x="511" y="133" width="76" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
+<text x="549" y="146" text-anchor="middle" dy="0.35em" font-size="10" font-weight="600" fill="var(--accent)">HTTP POST</text>
+
+<rect x="511" y="223" width="76" height="26" rx="13" fill="var(--accent-bg)" stroke="var(--accent-border)" stroke-width="0.5" />
+<text x="549" y="236" text-anchor="middle" dy="0.35em" font-size="10" font-weight="600" fill="var(--accent)">HTTP POST</text>
+
+<!-- ── App nodes (with icons) ── -->
+<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)" />
+<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)" />
+<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)" />
+
+<!-- GitHub icon (14x14) -->
+<g transform="translate(60,109) scale(0.109375)">
+ <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)"/>
+</g>
+<text x="79" y="116" text-anchor="start" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">GitHub</text>
+
+<!-- Slack icon (14x14) -->
+<g transform="translate(60,169) scale(0.109375)">
+ <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"/>
+ <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"/>
+ <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"/>
+ <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"/>
+ <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"/>
+ <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"/>
+ <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"/>
+ <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"/>
+</g>
+<text x="79" y="176" text-anchor="start" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">Slack</text>
+
+<!-- Gmail icon (14x14) -->
+<g transform="translate(60,229) scale(0.109375)">
+ <path d="M8.7275 113.854H29.091V64.4L0 42.5817V105.127C0 109.949 3.9055 113.855 8.7275 113.855V113.854Z" fill="#4285F4"/>
+ <path d="M98.909 113.854H119.273C124.095 113.854 128 109.949 128 105.127V42.5817L98.909 64.4V113.854Z" fill="#34A853"/>
+ <path d="M98.909 26.5817V64.4L128 42.5817V30.9455C128 20.16 115.687 14 107.054 20.4727L98.909 26.5817Z" fill="#FBBC04"/>
+ <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"/>
+ <path d="M0 30.9455V42.5817L29.091 64.4V26.5817L20.9455 20.4727C12.3125 14 0 20.16 0 30.945V30.9455Z" fill="#C5221F"/>
+</g>
+<text x="79" y="236" text-anchor="start" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">Gmail</text>
+
+<!-- Accent nodes (Webhook Receiver, Poller, Webhook Endpoint) -->
+<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)" />
+<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)" />
+<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)" />
+
+<!-- ── Composio + App node labels ── -->
+<text x="405" y="146" text-anchor="middle" dy="0.35em" font-size="12.5" font-weight="600" fill="var(--text)">Webhook Receiver</text>
+<text x="405" y="236" text-anchor="middle" dy="0.35em" font-size="13" font-weight="500" fill="var(--text)">Poller</text>
+<text x="730" y="191" text-anchor="middle" dy="0.35em" font-size="12.5" font-weight="600" fill="var(--text)">Webhook Endpoint</text>
+</svg>