Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs: split triggers index into creating-triggers and subscribing-to-events
Sushmithamallesh6ef299e6ba21
diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdxnew file mode 100644index 000000000..5a4a908c1--- /dev/null+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx@@ -0,0 +1,86 @@+---+title: Creating triggers+description: Create trigger instances via the dashboard or SDK+keywords: [triggers, create trigger, trigger config]+---++<Callout type="info" title="Prerequisites">+Before creating triggers, ensure you have:+- An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor+- A connected account for the user whose events you want to capture+</Callout>++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>diff --git a/docs/content/docs/setting-up-triggers/meta.json b/docs/content/docs/setting-up-triggers/meta.jsonindex 799358613..7c6564555 100644--- a/docs/content/docs/setting-up-triggers/meta.json+++ b/docs/content/docs/setting-up-triggers/meta.json@@ -1,7 +1,8 @@{"title": "Triggers","pages": [- "index",+ "creating-triggers",+ "subscribing-to-events","webhook-verification","managing-triggers"]diff --git a/docs/content/docs/setting-up-triggers/index.mdx b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdxsimilarity index 65%rename from docs/content/docs/setting-up-triggers/index.mdxrename to docs/content/docs/setting-up-triggers/subscribing-to-events.mdxindex b342efb56..467908fd5 100644--- a/docs/content/docs/setting-up-triggers/index.mdx+++ b/docs/content/docs/setting-up-triggers/subscribing-to-events.mdx@@ -1,93 +1,10 @@----title: Setting up triggers-description: Create trigger instances and subscribe to events via webhooks or SDK-keywords: [triggers, webhooks, subscribe, events, create trigger]+title: Subscribing to events+description: Receive trigger events via webhooks or SDK subscriptions+keywords: [webhooks, subscribe, events, webhook payload, V3]----<Callout type="info" title="Prerequisites">-Before setting up triggers, ensure you have:-- An [auth config](/docs/authentication#how-composio-manages-authentication) for the toolkit you want to monitor-- A connected account for the user whose events you want to capture-</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+## WebhooksWebhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.@@ -114,6 +31,7 @@ New organizations receive V3 payloads by default. V3 uses a standardized `type`"id": "msg_abc123","type": "composio.trigger.message","metadata": {+ "log_id": "log_abc123","trigger_slug": "GITHUB_COMMIT_EVENT","trigger_id": "ti_xyz789","connected_account_id": "ca_def456",@@ -185,7 +103,41 @@ export default async function webhookHandler(req: NextApiRequest, res: NextApiReAlways [verify webhook signatures](/docs/setting-up-triggers/webhook-verification) in production to ensure payloads are authentic.</Callout>-## Subscribing via SDK+### Handling connection expiry events++If you subscribe to `composio.connected_account.expired` events via the [Webhook Subscriptions API](/reference/api-reference/webhooks), Composio notifies you when an OAuth2 connection expires. The SDK provides typed schemas for these events:++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+from composio import is_connection_expired_event++def handle_webhook(payload: dict):+ if is_connection_expired_event(payload):+ account_id = payload["data"]["id"]+ toolkit = payload["data"]["toolkit"]["slug"]+ print(f"Connection {account_id} expired for {toolkit}")+ # Prompt user to re-authenticate+```+ </Tab>+ <Tab value="TypeScript">+```typescript+// @noErrors+import { ConnectionExpiredEventSchema } from '@composio/core';+// ---cut---+function handleWebhook(payload: unknown) {+ const result = ConnectionExpiredEventSchema.safeParse(payload);+ if (result.success) {+ const { data, metadata } = result.data;+ console.log(`Connection ${data.id} expired for ${data.toolkit.slug}`);+ // Prompt user to re-authenticate+ }+}+```+ </Tab>+</Tabs>++## SDK subscriptionsFor quick prototyping, you can subscribe to trigger events directly through the SDK without setting up a webhook endpoint.diff --git a/docs/content/docs/setting-up-triggers/webhook-verification.mdx b/docs/content/docs/setting-up-triggers/webhook-verification.mdxindex c534516a3..e5a12711b 100644--- a/docs/content/docs/setting-up-triggers/webhook-verification.mdx+++ b/docs/content/docs/setting-up-triggers/webhook-verification.mdx@@ -25,7 +25,7 @@ def webhook_handler():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", ""),+ id=request.headers.get("webhook-id", ""),timestamp=request.headers.get("webhook-timestamp", ""),secret=os.getenv("COMPOSIO_WEBHOOK_SECRET", ""),)@@ -78,6 +78,8 @@ The method throws an error if verification fails. On success it returns:| `payload` | `IncomingTriggerPayload` | Parsed and version-normalized event payload || `rawPayload` | `WebhookPayload` | Raw parsed payload before normalization |+Both methods accept an optional `tolerance` parameter (default: `300` seconds) that controls how old a webhook can be before verification fails. Set to `0` to disable timestamp validation.+## Manual verificationIf you're not using the Composio SDK (e.g., Go, Rust, or another language), verify signatures manually.@@ -161,6 +163,7 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep"id": "msg_abc123","type": "composio.trigger.message","metadata": {+ "log_id": "log_abc123","trigger_slug": "GITHUB_COMMIT_EVENT","trigger_id": "ti_xyz789","connected_account_id": "ca_def456",diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdxindex acb15cb05..a2292db26 100644--- a/docs/content/docs/triggers.mdx+++ b/docs/content/docs/triggers.mdx@@ -15,9 +15,9 @@ There are two delivery types:## Working with triggers-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. **Configure** your webhook endpoint so Composio knows where to deliver events+1. **Configure** your webhook endpoint so Composio knows where to deliver events+2. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)+3. **Create** an active trigger scoped to a user's connected account4. **Receive events**: Composio sends payloads to your endpoint5. **Manage**: enable, disable, or delete triggers as needed@@ -33,7 +33,8 @@ When you create a trigger from a type, it's scoped to a specific user and connec## Next steps<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" />+ <Card title="Creating triggers" href="/docs/setting-up-triggers/creating-triggers" description="Create trigger instances via the dashboard or SDK" />+ <Card title="Subscribing to events" href="/docs/setting-up-triggers/subscribing-to-events" description="Receive trigger events via webhooks or SDK subscriptions" />+ <Card title="Verifying webhooks" href="/docs/setting-up-triggers/webhook-verification" description="Verify webhook signatures and understand payload versions" />+ <Card title="Managing triggers" href="/docs/setting-up-triggers/managing-triggers" description="Discover, list, enable, disable, and delete triggers" /></Cards>