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
Update to triggers page in docs (#1906)
Sushmitha Malleshfd9367df961d
diff --git a/fern/assets/images/manage-triggers.png b/fern/assets/images/manage-triggers.pngdeleted file mode 100644index 6b807d7a8..000000000Binary files a/fern/assets/images/manage-triggers.png and /dev/null differdiff --git a/fern/assets/images/trigger-config.png b/fern/assets/images/trigger-config.pngindex f1f75c393..2a07003d9 100644Binary files a/fern/assets/images/trigger-config.png and b/fern/assets/images/trigger-config.png differdiff --git a/fern/assets/images/trigger-debug.png b/fern/assets/images/trigger-debug.pngdeleted file mode 100644index 1dbc63b10..000000000Binary files a/fern/assets/images/trigger-debug.png and /dev/null differdiff --git a/fern/assets/images/trigger-enable-disable.png b/fern/assets/images/trigger-enable-disable.pngnew file mode 100644index 000000000..6bb555c26Binary files /dev/null and b/fern/assets/images/trigger-enable-disable.png differdiff --git a/fern/assets/videos/enabling-triggers.mp4 b/fern/assets/videos/enabling-triggers.mp4index a8a0f4081..7a9f089f5 100644Binary files a/fern/assets/videos/enabling-triggers.mp4 and b/fern/assets/videos/enabling-triggers.mp4 differdiff --git a/fern/pages/src/triggers/using-triggers.mdx b/fern/pages/src/triggers/using-triggers.mdxindex b7fb7f502..b410df75a 100644--- a/fern/pages/src/triggers/using-triggers.mdx+++ b/fern/pages/src/triggers/using-triggers.mdx@@ -1,120 +1,99 @@---title: Using Triggerssubtitle: Send payloads to your AI agents or systems based on events in apps.-image: "https://og.composio.dev/api/og?title=Using%20Triggers" # image for socials-keywords: ''+image: 'https://og.composio.dev/api/og?title=Using%20Triggers' # image for socials+keywords: 'triggers, webhooks, websockets, events, active triggers'hide-nav-links: true----Triggers act as a notification system for your AI applications, enabling your agents to respond dynamically to external events occurring within your apps.+When **events** occur in connected apps (like new Slack messages or GitHub commits), triggers automatically send the event data to your application.--When these events take place, triggers capture relevant information and deliver structured payloads directly to your system, letting you build agents that respond proactively.+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.<Frame caption="Triggers through Composio" background="subtle"></Frame><Tip title="Prerequisites">- Before proceeding, ensure you've created an [auth config](/docs/authenticating-tools#creating-an-auth-config) and [established a connection](/docs/authenticating-tools#connecting-to-an-oauth-toolkit) to an app (e.g., Slack, GitHub).+ Before proceeding, ensure you've created an [auth+ config](/docs/authenticating-tools#creating-an-auth-config) and [established a+ connection](/docs/authenticating-tools#oauth-connections) to an app (e.g., Slack, GitHub).</Tip>## Creating a trigger-Head to any app that supports triggers, such as <a href="https://platform.composio.dev?next_page=/marketplace/slack" target="_blank">Slack</a> in the dashboard and enable the trigger of choice.+You can create triggers using either the Composio dashboard or programmatically via the SDK.+<Tabs><Tab title="Dashboard">-<video- src="../../../assets/videos/enabling-triggers.mp4"- width="854"- height="480"- autoplay- loop- playsinline- controls-></video>--<Frame caption="Triggers page" background="subtle">- <img src="../../../assets/images/manage-triggers.png" alt="Manage triggers" />-</Frame>--In some cases, triggers require certain configuration to set the correct events. You can inspect and add these properties while enabling the triggers.--The dashboard will show you the trigger configuration to fill in.--<Frame caption="Trigger configuration" background="subtle">+To create triggers through the **dashboard**:++- Navigate to the <a href="https://platform.composio.dev?next_page=%2Fauth-configs" target="_blank">Auth Configs</a> page+- Select the auth config+- Click "Add Trigger" and navigate to "Active Triggers" tab to fetch the trigger ID.+ <video+ src="../../../assets/videos/enabling-triggers.mp4"+ width="854"+ height="480"+ autoplay+ loop+ playsinline+ controls+ ></video>++Some triggers require additional configuration. The dashboard will prompt you for any required fields during setup.++<Frame caption="Example: Gmail trigger configuration" background="subtle"><imgsrc="../../../assets/images/trigger-config.png"- alt="Trigger configuration"+ alt="Trigger configuration example"width="400px"height="auto"/></Frame>-</Tab><Tab title="SDK">-You can also create triggers programmatically using the SDK. To get started, first view the required configuration for creating a trigger:-+Create triggers programmatically by providing the trigger type and any required configuration.<CodeGroup><SnippetCodesrc="fern/snippets/triggers/python/triggers.py"title="Python"startLine={1}- endLine={12}- highlightStart={10}- highlightEnd={10}+ endLine={18}+ highlightStart={12}+ highlightEnd={16}/><SnippetCodesrc="fern/snippets/triggers/typescript/triggers.ts"startLine={1}- endLine={13}- highlightStart={8}- highlightEnd={11}+ endLine={22}+ highlightStart={12}+ highlightEnd={21}title="TypeScript"/></CodeGroup>--Most triggers require certain configuration to send the correct events. For example, `GITHUB_COMMIT_EVENT` requires you to specify the repository and owner.--**Fetch required trigger configuration**--<CodeGroup>-<SnippetCode- src="fern/snippets/triggers/python/triggers.py"- startLine={13}- endLine={32}- title="Python"-/>--<SnippetCode- src="fern/snippets/triggers/typescript/triggers.ts"- startLine={5}- endLine={29}- title="TypeScript"-/>-</CodeGroup></Tab></Tabs>-## Subscribing to triggers-The typical and recommended way to subscribe to triggers is through webhooks.+### Webhooks-To receive trigger events via webhooks, you need to configure a publicly accessible URL where Composio can send the event payloads. This URL should point to an endpoint in your application that can process incoming webhook requests.+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).-<Tip title="Use ngrok/webhook.site for local dev!">-During development, you can use ngrok/webhook.site or other services to expose your local server to the internet.-</Tip>+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.-<Frame caption="Webhook setup" background="subtle">- <img src="../../../assets/images/setup-webhook.png" alt="Webhook setup" />-</Frame>+<Tip>+ **Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to+ expose your local server to the internet for testing.+</Tip>+**Implement your webhook handler:**-Below are some examples of how to listen in on trigger events for a FastAPI/Next.js application.+Below are some examples of how to listen in on trigger events+for a FastAPI/Next.js application.<CodeGroup><SnippetCode@@ -128,18 +107,31 @@ Below are some examples of how to listen in on trigger events for a FastAPI/Next/></CodeGroup>+### 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.++<CodeGroup>+ <SnippetCode src="fern/snippets/triggers/python/trigger-subscription.py" title="Python" />+ <SnippetCode src="fern/snippets/triggers/typescript/trigger-subscription.ts" title="Typescript" />+</CodeGroup>+## Trigger payload types-When subscribing to triggers, it is helpful to know the payload type received from the trigger. You can inspect the payload type by fetching the trigger type.++To see what data you'll receive in your webhook handler, inspect the trigger's payload:<CodeGroup>```python Python maxLines=60 wordWrap-# Get a trigger by id+# Get trigger type to inspect payload structuretrigger = composio.triggers.get_type(slug="GITHUB_COMMIT_EVENT")print(trigger.payload)``````typescript TypeScript maxLines=60 wordWrap-const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");+// Get trigger type to inspect payload structure+const triggerType = await composio.triggers.getType('GITHUB_COMMIT_EVENT');console.log(triggerType.payload);```@@ -167,80 +159,63 @@ For better type safety and developer experience in TypeScript, you can define sp</CodeGroup>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-## Prototyping triggers during development-During development, you may not have a proper webhook setup -- so you can subscribe to triggers directly through the SDK.+### Enable/disable triggers-You 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.+You can pause triggers temporarily without deleting them.-This method uses WebSocket to subscribe to the trigger.+<Tabs>+<Tab title="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-<CodeGroup>-```python Python maxLines=60 wordWrap-user_id = "[email protected]"+<Frame caption="Enable/disable triggers" background="subtle">+ <img+ src="../../../assets/images/trigger-enable-disable.png"+ alt="Enable/disable triggers"+ width="400px"+ height="auto"+ />+</Frame>+</Tab>-# Subscribe to a trigger-subscription = composio.triggers.subscribe()+<Tab title="SDK">+<CodeGroup>+```python Python+# Disable a trigger+composio.triggers.disable(trigger_id="ti_abcd123")-# Define a handler[email protected](toolkit="GITHUB", user_id=user_id)-def handle_github_event(data):- print(data)-```-```typescript TypeScript maxLines=60 wordWrap-await composio.triggers.subscribe(- triggerData => {- console.log('Received trigger:', triggerData);- },- {- triggerId: 'ti_So9EQf8XnAcy',- // userId: '[email protected]',- // toolkits: ['github', 'slack'],- // triggerSlug: ["GITHUB_STAR_ADDED_EVENT"]- // authConfigId: "ac_1234567890"- }-)-```-</CodeGroup>+# Re-enable when needed-## Enabling/Disabling triggers+composio.triggers.enable(trigger_id="ti_abcd123")-In cases where the trigger isn't required for the system, it can be disabled.+````+``` typescript TypeScript+// Disable a trigger+await composio.triggers.disable('ti_abcd123');-<CodeGroup>- ```python Python maxLines=60 wordWrap- # Disable a trigger instance- disabled_instance = composio.triggers.disable(trigger_id="ti_abcd123")- print(disabled_instance)- ```- ```typescript TypeScript maxLines=60 wordWrap- await composio.triggers.disable("ti_abcd123");- ```-</CodeGroup>+// Re-enable when needed+await composio.triggers.enable('ti_abcd123');-If needed, the trigger can be enabled again.+````-<CodeGroup>- ```python Python maxLines=60 wordWrap- # Enable a trigger instance- enabled_instance = composio.triggers.enable(trigger_id="ti_abcd123")- print(enabled_instance)- ```- ```typescript TypeScript maxLines=60 wordWrap- await composio.triggers.enable("ti_abcd123");- ```</CodeGroup>+</Tab>+</Tabs>## Troubleshooting-If you encounter issues with triggers or webhook listeners, you can use the Composio dashboard to inspect detailed trigger logs. The dashboard allows you to review event payloads, identify errors, and manually resend events for testing purposes.-Access the trigger logs <a href="https://platform.composio.dev?next_page=/logs/triggers" target="_blank">here</a>.+View detailed trigger logs and debug issues on the [Composio dashboard](https://platform.composio.dev?next_page=/logs/triggers).-<Frame caption="Trigger logs" background="subtle">- <img src="../../../assets/images/trigger-debug.png" alt="Trigger logs" />-</Frame>\ No newline at end of file+```++```diff --git a/fern/snippets/triggers/python/trigger-subscription.py b/fern/snippets/triggers/python/trigger-subscription.pynew file mode 100644index 000000000..453445040--- /dev/null+++ b/fern/snippets/triggers/python/trigger-subscription.py@@ -0,0 +1,15 @@+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++# Note: For production use, set up webhooks insteaddiff --git a/fern/snippets/triggers/python/triggers.py b/fern/snippets/triggers/python/triggers.pyindex cbabf1247..1b753e26d 100644--- a/fern/snippets/triggers/python/triggers.py+++ b/fern/snippets/triggers/python/triggers.py@@ -1,32 +1,17 @@from composio import Composio-composio = Composio()+composio = Composio(api_key="your-api-key")+user_id = "user-id-123435"-user_id = "[email protected]"+# 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 configtrigger = composio.triggers.create(slug="GITHUB_COMMIT_EVENT",user_id=user_id,- trigger_config={"repo": "composiohq", "owner": "composio"},+ trigger_config={"owner": "your-repo-owner", "repo": "your-repo-name"},)-print(trigger)--trigger_config = composio.triggers.get_type("GITHUB_COMMIT_EVENT")-print(trigger_config.config)-### Trigger Config-# {-# "properties": {-# "owner": {-# "description": "Owner of the repository",-# "title": "Owner",-# "type": "string"-# },-# "repo": {-# "description": "Repository name",-# "title": "Repo",-# "type": "string"-# }-# },-# "required": ["owner", "repo"],-# "title": "WebhookConfigSchema",-# "type": "object"\ No newline at end of file+print(f"Trigger created: {trigger.trigger_id}")diff --git a/fern/snippets/triggers/typescript/trigger-subscription.ts b/fern/snippets/triggers/typescript/trigger-subscription.tsnew file mode 100644index 000000000..6b3c0dcb2--- /dev/null+++ b/fern/snippets/triggers/typescript/trigger-subscription.ts@@ -0,0 +1,20 @@+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'+ // userId: '[email protected]',+ // toolkits: ['github', 'slack'],+ // triggerSlug: ["GITHUB_STAR_ADDED_EVENT"]+ // authConfigId: "ac_1234567890" }+ }+);++// Note: For production use, set up webhooks instead\ No newline at end of filediff --git a/fern/snippets/triggers/typescript/triggers.ts b/fern/snippets/triggers/typescript/triggers.tsindex 84f7287bf..bd86575a2 100644--- a/fern/snippets/triggers/typescript/triggers.ts+++ b/fern/snippets/triggers/typescript/triggers.ts@@ -1,59 +1,22 @@import { Composio } from '@composio/core';-const composio = new Composio();-const userId = '[email protected]';--// Create the trigger-const createResponse = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {- triggerConfig: {- owner: 'composiohq',- repo: 'composio',- },-});-console.log(createResponse);---// Fetch the trigger details-const triggerType = await composio.triggers.getType("GITHUB_STAR_ADDED_EVENT");-console.log(triggerType.config)-/*--- Trigger config ----{- "properties": {- "owner": {- "description": "Owner of the repository",- "title": "Owner",- "type": "string"- },- "repo": {- "description": "Repository name",- "title": "Repo",- "type": "string"- }- },- "required": [- "owner",- "repo"- ],- "title": "WebhookConfigSchema",- "type": "object"- }-*/---// Create the trigger-await composio.triggers.subscribe(- triggerData => {- console.log('Received trigger:', triggerData);- },- {- // triggerId: 'ti_9q19nLNykmVZ',- // toolkits: ['GITHUB']- // userId: "sid",- // triggerSlug: ["GITHUB_COMMIT_EVENT"]- authConfigId: 'ac_1234567890',- }+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'+ }+ });--await composio.triggers.enable('ti_9q19nLNykmVZ');-await composio.triggers.disable('ti_9q19nLNykmVZ');-+console.log(`Trigger created: ${trigger.triggerId}`);\ No newline at end of file