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(creating-triggers): revert unrelated edits, reorder Configuring before SDK, fix bullet wording, single PATCH
Anshu Gargdf3405acd6d3
diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdxindex b35aebbc7..0f5f2fc58 100644--- a/docs/content/docs/setting-up-triggers/creating-triggers.mdx+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx@@ -1,6 +1,6 @@---title: Creating triggers-description: Inspect a trigger type and create the instance via the SDK or the dashboard+description: Create trigger instances via the dashboard or SDKkeywords: [triggers, create trigger, trigger config]---@@ -14,78 +14,6 @@ Create a trigger to start receiving events. A trigger watches for a specific eveYou can create triggers using the [SDK](#using-the-sdk) or the Composio [dashboard](#using-the-dashboard). Some webhook triggers also need a webhook endpoint configured first — covered in [Configuring the webhook endpoint](#configuring-the-webhook-endpoint) below.-## Using the SDK--Before creating a trigger, inspect the trigger type. The response tells you what config it requires and whether you need to set up a webhook endpoint first.--<Callout>-When you pass a `user_id`, the SDK automatically finds the user's connected account for the relevant toolkit. If the user has multiple connected accounts for the same toolkit, it uses the most recently created one. You can also pass a `connected_account_id`/`connectedAccountId` directly if you need more control.-</Callout>--<Tabs groupId="language" items={['Python', 'TypeScript']} persist>- <Tab value="Python">-```python-from composio import Composio--composio = Composio()-user_id = "user-id-123435"--# Inspect the trigger type-trigger_type = composio.triggers.get_type("GITHUB_COMMIT_EVENT")-print(trigger_type.config)-# {"properties": {"owner": {...}, "repo": {...}}, "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();-const userId = 'user-id-123435';--// Inspect the trigger type-const triggerType = await composio.triggers.getType("GITHUB_COMMIT_EVENT");-console.log(triggerType.config);-// {"properties": {"owner": {...}, "repo": {...}}, "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>-Trigger instances default to the `'latest'` toolkit version. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.-</Callout>--## Using the dashboard--1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit-2. Navigate to **Active Triggers** and click **Create Trigger**-3. Select the connected account for which you want to create a trigger-4. Choose a trigger type and fill in the required configuration. If the trigger requires a webhook endpoint, the dashboard prompts you to configure one before saving.-5. Click **Create Trigger**--<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />-## Configuring the webhook endpointSome webhook triggers require a webhook endpoint registered with the provider before they can fire. With Composio-managed OAuth, this is already done for you. You only run the steps below when you bring your own OAuth app and the trigger type's `requires_webhook_endpoint_setup` flag is `true`.@@ -99,7 +27,7 @@ https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trA single OAuth app can serve at most one Composio project: providers accept only one callback URL per OAuth app, and each ingress URL routes to a single project. In return, every project becomes its own webhook tenant — with:- **Its own ingress rate limit and backpressure budget**-- **Its own signing secret and app-level token**, scoped to this project alone. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped by a forged challenge.+- **Project-scoped credentials** — the signing secret and app-level token you provide are stored against this project alone, never shared across projects. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped by a forged challenge.- **Clean fan-out** — events reach only that project's trigger instances- **Per-project metering**@@ -175,7 +103,7 @@ Hold on to two values from the response: `id` (used as `<ENDPOINT_ID>` below) an### Step 3: Store the credentials returned by the schema-`PATCH` each field returned by the schema. For Slack, that's the signing secret and (when applicable) the app-level token.+`PATCH` all the fields the schema returned in a single request. For Slack, that's the signing secret and (when needed) the app-level token together:```bashcurl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \@@ -183,32 +111,21 @@ curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT-H "Content-Type: application/json" \-d '{"data": {- "webhook_signing_secret": "<SIGNING_SECRET>"+ "webhook_signing_secret": "<SIGNING_SECRET>",+ "app_token": "xapp-..."}}'```-For Slack, the signing secret lives at **Slack app → Basic Information → App Credentials → Signing Secret**.+For Slack, the credentials come from:++- **Signing secret** — Slack app → Basic Information → App Credentials → Signing Secret.+- **App-level token** — Slack app → Basic Information → App-Level Tokens, with scope `authorizations:read`. Required for direct messages, private channels, and reactions; omit it if you only need public-channel events.<Callout type="warn">**Store the credentials before you switch the provider's callback URL in step 4.** If the provider posts to the URL without a secret on the endpoint, every request fails with `400`, and the provider may auto-disable the endpoint after a window of consecutive failures (Slack: ~36 hours).</Callout>-For toolkits with additional fields — Slack's `app_token`, for instance, which is required for direct messages, private channels, and reactions — `PATCH` them in the same way:--```bash-curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \- -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \- -H "Content-Type: application/json" \- -d '{- "data": {- "app_token": "xapp-..."- }- }'-```--Generate the Slack app-level token from **Slack app → Basic Information → App-Level Tokens** with scope `authorizations:read`.-### Step 4: Point the provider's app dashboard at the URLPaste the `webhook_url` from step 2 into the provider's app dashboard:@@ -216,7 +133,7 @@ Paste the `webhook_url` from step 2 into the provider's app dashboard:- **Slack** → Event Subscriptions → Request URL- **Notion** → Webhook Endpoints (in the integration's settings)-For providers that issue a verification challenge on save (Slack `url_verification`, Notion's verification token, and so on), Composio responds automatically — no handshake code on your side. Once the provider accepts the URL, head back to [Using the SDK](#using-the-sdk) to create your trigger.+For providers that issue a verification challenge on save (Slack `url_verification`, Notion's verification token, and so on), Composio responds automatically — no handshake code on your side. Once the provider accepts the URL, continue to [Using the SDK](#using-the-sdk) to create your trigger.### Updating an endpoint@@ -254,6 +171,78 @@ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \-H "x-api-key: <YOUR_COMPOSIO_API_KEY>"```+## 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.++<Callout>+When you pass a `user_id`, the SDK automatically finds the user's connected account for the relevant toolkit. If the user has multiple connected accounts for the same toolkit, it uses the most recently created one. You can also pass a `connected_account_id`/`connectedAccountId` directly if you need more control.+</Callout>++<Tabs groupId="language" items={['Python', 'TypeScript']} persist>+ <Tab value="Python">+```python+from composio import Composio++composio = Composio()+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": {"owner": {...}, "repo": {...}}, "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();+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": {"owner": {...}, "repo": {...}}, "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>+Trigger instances default to the `'latest'` toolkit version. If your code parses trigger payloads programmatically against a fixed schema, you can pin a specific version at SDK initialization. See [Toolkit Versioning](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) for details.+</Callout>++## Using the dashboard++1. Navigate to [Auth Configs](https://platform.composio.dev?next_page=%2Fauth-configs) and select the auth config for the relevant toolkit+2. Navigate to **Active Triggers** and click **Create Trigger**+3. Select the connected account for which you want to create a trigger+4. Choose a trigger type and fill in the required configuration+5. Click **Create Trigger**++<Video src="/videos/triggers-creation.mp4" caption="Creating a GitHub Star Added trigger from the dashboard" />+## What to read next<Cards>