Triggers API

The triggers API manages webhook triggers that notify your application when events occur in connected services. Triggers enable real-time integrations without polling.

Methods

listActive()

List all active trigger instances.

async listActive(
  query?: TriggerInstanceListActiveParams
): Promise<TriggerInstanceListActiveResponse>

query

TriggerInstanceListActiveParams

Show properties

authConfigIds

string[]

Filter by auth config IDs

connectedAccountIds

string[]

Filter by connected account IDs

triggerIds

string[]

Filter by trigger IDs

triggerNames

string[]

Filter by trigger names

showDisabled

boolean

Include disabled triggers

cursor

string

Pagination cursor

limit

number

Maximum results

Example:

const triggers = await composio.triggers.listActive({
  connectedAccountIds: ['conn_abc123'],
  limit: 20
});

triggers.items.forEach(trigger => {
  console.log(trigger.triggerId, trigger.triggerSlug);
});

create()

Create a new trigger instance for a user.

async create(
  userId: string,
  slug: string,
  body?: TriggerInstanceUpsertParams
): Promise<TriggerInstanceUpsertResponse>

userId

string

required

User ID to create trigger for

slug

string

required

Trigger slug (e.g., GITHUB_PULL_REQUEST_EVENT)

body

TriggerInstanceUpsertParams

Show properties

connectedAccountId

string

Specific connected account to use. If not provided, uses the first available.

triggerConfig

Record<string, unknown>

Trigger-specific configuration

Basic trigger
With config
Specific account

const trigger = await composio.triggers.create(
  'user_123',
  'GITHUB_PULL_REQUEST_EVENT'
);

console.log('Trigger created:', trigger.triggerId);

const trigger = await composio.triggers.create(
  'user_123',
  'SLACK_RECEIVE_MESSAGE',
  {
    triggerConfig: {
      channel: '#alerts',
      keywords: ['error', 'critical']
    }
  }
);

const trigger = await composio.triggers.create(
  'user_123',
  'GMAIL_NEW_EMAIL_RECEIVED',
  {
    connectedAccountId: 'conn_abc123'
  }
);

update()

Update an existing trigger instance.

async update(
  triggerId: string,
  body: TriggerInstanceManageUpdateParams
): Promise<TriggerInstanceManageUpdateResponse>

Example:

await composio.triggers.update('trigger_abc123', {
  status: 'enable'
});

delete()

Delete a trigger instance.

async delete(triggerId: string): Promise<TriggerInstanceManageDeleteResponse>

Example:

await composio.triggers.delete('trigger_abc123');
console.log('Trigger deleted');

enable() / disable()

Enable or disable a trigger instance.

async enable(triggerId: string): Promise<TriggerInstanceUpsertResponse>
async disable(triggerId: string): Promise<TriggerInstanceUpsertResponse>

Example:

// Temporarily disable a trigger
await composio.triggers.disable('trigger_abc123');

// Re-enable it later
await composio.triggers.enable('trigger_abc123');

listTypes()

List all available trigger types.

async listTypes(query?: TriggersTypeListParams): Promise<TriggersTypeListResponse>

query

TriggersTypeListParams

Show properties

toolkits

string[]

Filter by toolkit slugs

cursor

string

Pagination cursor

limit

number

Maximum results

Example:

const triggerTypes = await composio.triggers.listTypes({
  toolkits: ['github', 'slack']
});

triggerTypes.items.forEach(type => {
  console.log(type.slug, type.description);
});

getType()

Retrieve a specific trigger type.

async getType(slug: string): Promise<TriggersTypeRetrieveResponse>

Example:

const triggerType = await composio.triggers.getType('GITHUB_PULL_REQUEST_EVENT');

console.log(triggerType.name); // "Pull Request Event"
console.log(triggerType.description); // "Triggered when..."
console.log(triggerType.inputSchema); // Configuration schema

Subscribe to trigger events via Pusher.

async subscribe(
  fn: (data: IncomingTriggerPayload) => void,
  filters?: TriggerSubscribeParams
): Promise<void>

function

required

Callback function to handle trigger events

filters

TriggerSubscribeParams

Show properties

toolkits

string[]

Filter by toolkit slugs

triggerId

string

Specific trigger ID

connectedAccountId

string

Specific connected account

triggerSlug

string[]

Filter by trigger slugs

userId

string

Filter by user ID

Subscribe to all triggers
Filter by toolkit
Filter by user

await composio.triggers.subscribe(
  (data) => {
    console.log('GitHub event:', data.triggerSlug);
    console.log('Data:', data.payload);
  },
  { toolkits: ['github'] }
);

await composio.triggers.subscribe(
  (data) => {
    console.log('User event:', data);
  },
  { userId: 'user_123' }
);

unsubscribe()

Unsubscribe from trigger events.

async unsubscribe(): Promise<void>

Example:

// Subscribe to triggers
await composio.triggers.subscribe((data) => {
  console.log('Trigger:', data);
});

// Later, unsubscribe
await composio.triggers.unsubscribe();

verifyWebhook()

Verify an incoming webhook payload and signature.

async verifyWebhook(params: VerifyWebhookParams): Promise<VerifyWebhookResult>

params

VerifyWebhookParams

required

Show properties

payload

string

required

Raw webhook payload (request body)

signature

string

required

Value from webhook-signature header

string

required

Value from webhook-id header

timestamp

string

required

Value from webhook-timestamp header

secret

string

required

Your webhook secret from Composio dashboard

tolerance

number

default:300

Maximum webhook age in seconds (0 to disable)

Express.js
Next.js API Route

import express from 'express';

const app = express();

app.post('/webhook',
  express.raw({ type: 'application/json' }),
  async (req, res) => {
    try {
      const result = await composio.triggers.verifyWebhook({
        payload: req.body.toString(),
        signature: req.headers['webhook-signature'] as string,
        id: req.headers['webhook-id'] as string,
        timestamp: req.headers['webhook-timestamp'] as string,
        secret: process.env.COMPOSIO_WEBHOOK_SECRET!
      });

      console.log('Webhook version:', result.version);
      console.log('Trigger:', result.payload.triggerSlug);
      console.log('Data:', result.payload.payload);

      res.status(200).send('OK');
    } catch (error) {
      console.error('Webhook verification failed:', error);
      res.status(401).send('Unauthorized');
    }
  }
);

// app/api/webhook/route.ts
import { NextRequest, NextResponse } from 'next/server';

export async function POST(request: NextRequest) {
  const payload = await request.text();

  try {
    const result = await composio.triggers.verifyWebhook({
      payload,
      signature: request.headers.get('webhook-signature')!,
      id: request.headers.get('webhook-id')!,
      timestamp: request.headers.get('webhook-timestamp')!,
      secret: process.env.COMPOSIO_WEBHOOK_SECRET!
    });

    // Process the verified webhook
    console.log('Trigger:', result.payload.triggerSlug);

    return NextResponse.json({ success: true });
  } catch (error) {
    return NextResponse.json(
      { error: 'Verification failed' },
      { status: 401 }
    );
  }
}

Types

IncomingTriggerPayload

interface IncomingTriggerPayload {
  id: string; // Trigger instance ID
  uuid: string; // Unique event ID
  triggerSlug: string; // Trigger type (e.g., GITHUB_PULL_REQUEST_EVENT)
  toolkitSlug: string; // Toolkit that fired the trigger
  userId: string; // User ID
  payload: Record<string, unknown>; // Event data
  originalPayload: Record<string, unknown>; // Raw event from service
  metadata: {
    id: string;
    uuid: string;
    triggerSlug: string;
    toolkitSlug: string;
    triggerConfig: Record<string, unknown>;
    connectedAccount: {
      id: string;
      uuid: string;
      authConfigId: string;
      userId: string;
      status: string;
    };
  };
}

VerifyWebhookResult

interface VerifyWebhookResult {
  version: 'V1' | 'V2' | 'V3'; // Webhook format version
  payload: IncomingTriggerPayload; // Parsed trigger data
  rawPayload: WebhookPayload; // Original webhook payload
}

Common Triggers

GitHub

GITHUB_PULL_REQUEST_EVENT - PR opened, closed, or updated
GITHUB_COMMIT_EVENT - New commits pushed
GITHUB_ISSUE_EVENT - Issues created or updated
GITHUB_STAR_ADDED - Repository starred

Slack

SLACK_RECEIVE_MESSAGE - Message posted to channel
SLACK_RECEIVE_REACTION - Reaction added to message
SLACK_CHANNEL_CREATED - New channel created

Gmail

GMAIL_NEW_EMAIL_RECEIVED - New email received
GMAIL_NEW_LABELED_EMAIL - Email labeled

Best Practices

Webhook Verification: Always verify webhooks in production
Error Handling: Handle trigger failures gracefully
Idempotency: Use uuid to prevent duplicate processing
Filtering: Use filters to reduce unnecessary events
Unsubscribe: Clean up subscriptions when done

Next Steps

Connected Accounts

Set up user authentication

Tools API

Execute tools from triggers

Toolkits

Browse available toolkits

Auth Configs

Configure authentication

Overview

Core API

Providers

Advanced

Methods

listActive()

create()

update()

delete()

enable() / disable()

listTypes()

getType()

unsubscribe()

verifyWebhook()

Types

IncomingTriggerPayload

VerifyWebhookResult

Common Triggers

GitHub

Slack

Gmail

Best Practices

Next Steps

Connected Accounts

Tools API

Toolkits

Auth Configs

Build docs developers (and LLMs) love

Overview

Core API

Providers

Advanced

​Methods

​listActive()

​create()

​update()

​delete()

​enable() / disable()

​listTypes()

​getType()

​subscribe()

​unsubscribe()

​verifyWebhook()

​Types

​IncomingTriggerPayload

​VerifyWebhookResult

​Common Triggers

​GitHub

​Slack

​Gmail

​Best Practices

​Next Steps

Connected Accounts

Tools API

Toolkits

Auth Configs

Build docs developers (and LLMs) love

Methods

listActive()

create()

update()

delete()

enable() / disable()

listTypes()

getType()

subscribe()

unsubscribe()

verifyWebhook()

Types

IncomingTriggerPayload

VerifyWebhookResult

Common Triggers

GitHub

Slack

Gmail

Best Practices

Next Steps