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

Most trigger types can be created after the user has a connected account. Some webhook trigger types also require a provider-facing Composio webhook endpoint before you create the trigger instance. This endpoint is the URL the provider calls when an event occurs; it is separate from the webhook subscription where Composio sends normalized events to your app.

Slack trigger types that use this setup are:

Trigger type	Notes
`SLACK_CHANNEL_MESSAGE_RECEIVED`	Public channels work with the Slack signing secret. Private channels and multi-person DMs also require an app-level token.
`SLACK_DIRECT_MESSAGE_RECEIVED`	Requires an app-level token.
`SLACK_MESSAGE_REACTION_ADDED`	Requires an app-level token.

Legacy Slack trigger types such as SLACK_RECEIVE_MESSAGE, SLACK_RECEIVE_DIRECT_MESSAGE, and SLACK_REACTION_ADDED do not require this setup.

If a trigger type requires a provider webhook endpoint and no endpoint exists for the OAuth app in the current project, trigger creation fails with 400.

Set up a Slack webhook endpoint

Use the Webhook Endpoints API with your project API key.

Check the required setup fields

curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=slack" \
  -H "x-api-key: YOUR_API_KEY"

Create the endpoint for your Slack OAuth app

curl -X POST "https://backend.composio.dev/api/v3.1/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 an endpoint id and a webhook_url. The request is idempotent for the same toolkit_slug and client_id in a project.

Store Slack setup data on the endpoint

Store the Slack signing secret before setting the Slack Request URL to this endpoint:

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

For private channels, direct messages, multi-person DMs, and reaction events, also store a Slack app-level token with the authorizations:read scope:

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

Configure the provider callback URL

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

A provider OAuth app should map to one Composio project for provider webhook endpoint triggers. If multiple Composio projects need these trigger types, create a separate provider OAuth app for each project so each app can use its own callback URL and signing secret.

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

Set up a Slack webhook endpoint

Using the SDK

Using the dashboard

What to read next

Subscribing to events

Managing triggers

On this page