Using Triggers

When events occur in connected apps (like new Slack messages or GitHub commits), triggers automatically send the event data to your application.

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.

Creating a trigger

You can create triggers using either the Composio dashboard or programmatically via the SDK.

Dashboard

SDK

To create triggers through the dashboard:

• Navigate to the Auth Configs page
• Select the auth config
• Click “Add Trigger” and navigate to “Active Triggers” tab to fetch the trigger ID.

Some triggers require additional configuration. The dashboard will prompt you for any required fields during setup.

Subscribing to triggers

Webhooks

The recommended way to subscribe to triggers is through webhooks. Configure your webhook URL in the Event & Trigger settings.

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.

Implement your webhook handler:

Below are some examples of how to listen in on trigger events for a FastAPI/Next.js application.

1
from fastapi import FastAPI, Request
2
from typing import Dict, Any
3
import uvicorn
4
import json
5
6
app = FastAPI(title="Webhook Demo")
7
8
@app.post("/webhook")
9
async def webhook_handler(request: Request):
10
    # Get the raw payload
11
    payload = await request.json()
12
    
13
    # Log the received webhook data
14
    print("Received webhook payload:")
15
    print(json.dumps(payload, indent=2))
16
    
17
    # Return a success response
18
    return {"status": "success", "message": "Webhook received"}
19
20
if __name__ == "__main__":
21
    uvicorn.run(app, host="0.0.0.0", port=8000)

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.

1
from composio import Composio
2
3
# Initialize Composio client
4
composio = Composio(api_key="your_api_key_here")
5
6
# Subscribe to trigger events
7
subscription = composio.triggers.subscribe()
8
9
# Define event handler
10
@subscription.handle(trigger_id="your_trigger_id")
11
def handle_github_commit(data):
12
  print(f"New commit detected: {data}")
13
  # Add your custom logic here
14
15
# Note: For production use, set up webhooks instead

Trigger payload types

To see what data you’ll receive in your webhook handler, inspect the trigger’s payload:

1
# Get trigger type to inspect payload structure
2
trigger = composio.triggers.get_type(slug="GITHUB_COMMIT_EVENT")
3
print(trigger.payload)

Type-safe trigger handling (TypeScript)

For better type safety and developer experience in TypeScript, you can define specific payload types and use the TriggerEvent<T> interface:

1
// Define type-safe payload for GitHub Star Added event
2
export type GitHubStarAddedEventPayload = {
3
  action: "created";
4
  repository_id: number;
5
  repository_name: string;
6
  repository_url: string;
7
  starred_at: string;
8
  starred_by: string;
9
};
10
11
const composio = new Composio();
12
const userId = 'user@acme.com';
13
14
// Create the trigger
15
const createResponse = await composio.triggers.create(userId, 'GITHUB_STAR_ADDED_EVENT', {
16
  triggerConfig: {
17
    owner: 'composiohq',
18
    repo: 'composio',
19
  },
20
});
21
22
// Fetch trigger type details
23
const triggerType = await composio.triggers.getType("GITHUB_STAR_ADDED_EVENT");
24
console.log(triggerType.config);

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

Enable/disable triggers

You can pause triggers temporarily without deleting them.

Dashboard

SDK

1. Go to the Auth Config page
2. Select your auth config
3. Navigate to “Active Triggers”
4. Disable/Enable the trigger

Troubleshooting

View detailed trigger logs and debug issues on the Composio dashboard.