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: 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.mdx
new file mode 100644
index 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.json
index 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.mdx
similarity index 65%
rename from docs/content/docs/setting-up-triggers/index.mdx
rename to docs/content/docs/setting-up-triggers/subscribing-to-events.mdx
index 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
+## Webhooks
Webhooks 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: NextApiRe
Always [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 subscriptions
For 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.mdx
index 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 verification
If 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.mdx
index 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 account
4. **Receive events**: Composio sends payloads to your endpoint
5. **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>