Triggers API

Manage webhook triggers and real-time event subscriptions

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

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

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

With config

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

Specific account

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()

Subscribe to trigger events via Pusher.

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

fn · 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

await composio.triggers.subscribe((data) => {
  console.log('Trigger received:', data.triggerSlug);
  console.log('Payload:', data.payload);
});

Filter by toolkit

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

Filter by user

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

id · 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

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

Next.js API Route

// 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

1. Webhook Verification: Always verify webhooks in production
2. Error Handling: Handle trigger failures gracefully
3. Idempotency: Use uuid to prevent duplicate processing
4. Filtering: Use filters to reduce unnecessary events
5. 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