Creating triggers

Create a trigger to start receiving events. A trigger watches for a specific event (e.g., GITHUB_COMMIT_EVENT) on a specific user's connected account. For an overview of how triggers work, see Triggers.

Prerequisites

Before creating triggers, ensure you have:

An auth config for the toolkit you want to monitor
A connected account for the user whose events you want to capture

You can create triggers using the SDK or the Composio dashboard.

Provider webhook endpoints

Some webhook-based trigger types require a provider-facing webhook endpoint before you create the trigger instance. This endpoint is where the external app sends events to Composio. It is separate from the webhook subscription where Composio sends trigger events to your application.

Slack's V2 trigger slugs use dedicated webhook endpoints:

Trigger slug	When an app-level token is required
`SLACK_CHANNEL_MESSAGE_RECEIVED`	Private channels and multi-person DMs
`SLACK_DIRECT_MESSAGE_RECEIVED`	Always
`SLACK_MESSAGE_REACTION_ADDED`	Always

Create the webhook endpoint

Use the same project API key as the project that owns the Slack auth config:

curl -X POST "https://backend.composio.dev/api/v3/webhook_endpoints" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "toolkit_slug": "slack", "client_id": "YOUR_SLACK_CLIENT_ID" }'

The response includes a webhook_url and endpoint id. The create call is idempotent for the same toolkit_slug and client_id within a project.

Store Slack endpoint secrets

Patch the endpoint with your Slack signing secret. Add an app-level token when you need private-channel, direct-message, or reaction events:

curl -X PATCH "https://backend.composio.dev/api/v3/webhook_endpoints/ENDPOINT_ID" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "data": {
      "webhook_signing_secret": "YOUR_SIGNING_SECRET",
      "app_token": "xapp-..."
    }
  }'

Create the Slack app-level token from Basic Information > App-Level Tokens with the authorizations:read scope.

Set the Slack request URL

In your Slack app, set Event Subscriptions > Request URL to the webhook_url returned when you created the endpoint. Composio handles Slack URL verification automatically.

Store the Slack signing secret before changing the Slack request URL. If Slack sends events to a V2 endpoint before the secret is configured, Composio rejects the requests.

After the endpoint is configured, create the trigger instance with the V2 slug. For example:

curl -X POST "https://backend.composio.dev/api/v3/trigger_instances/SLACK_CHANNEL_MESSAGE_RECEIVED/upsert" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "connected_account_id": "CONNECTED_ACCOUNT_ID",
    "trigger_config": {}
  }'

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.

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.

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}")

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}`);

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 for details.

Using the dashboard

Navigate to Auth Configs and select the auth config for the relevant toolkit
Navigate to Active Triggers and click Create Trigger
Select the connected account for which you want to create a trigger
Choose a trigger type and fill in the required configuration
Click Create Trigger

Creating a GitHub Star Added trigger from the dashboard

Creating triggers

Provider webhook endpoints

Using the SDK

Using the dashboard

What to read next

Subscribing to events

Managing triggers

On this page