Triggers API — Composio TypeScript SDK Reference

The Triggers class enables real-time event-driven automation. When a trigger fires — a new email arrives, a GitHub PR is opened, a Slack message is posted — Composio delivers the event to your callback via Pusher WebSocket or HTTPS webhook. Triggers are attached to connected accounts, so each user’s events are isolated. Subscribe to all incoming trigger events with optional filters. Maintains a persistent WebSocket connection using Pusher.

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

function

required

Callback invoked for each matching trigger event. Receives an IncomingTriggerPayload.

filters

TriggerSubscribeParams

Filter which trigger events are forwarded to your callback. All filters are ANDed together.

Show TriggerSubscribeParams fields

toolkits

string[]

Only receive events from specified toolkit slugs (e.g. ['github', 'gmail']).

triggerSlug

string[]

Only receive events matching specific trigger slugs (e.g. ['GMAIL_NEW_EMAIL']).

connectedAccountId

string

Only receive events from a specific connected account.

triggerId

string

Only receive events from a specific trigger instance.

userId

string

Only receive events for a specific user.

triggerData

string

Match on the trigger’s metadata data field.

authConfigId

string

Only receive events from connections under a specific auth config.

IncomingTriggerPayload

string

Trigger instance ID.

uuid

string

Trigger UUID.

triggerSlug

string

The trigger type slug (e.g. 'GMAIL_NEW_EMAIL').

toolkitSlug

string

The toolkit that fired the event (e.g. 'GMAIL').

userId

string

The user ID associated with the connected account that fired this event.

payload

Record<string, unknown>

The trigger’s event-specific data (e.g. email subject, body, sender for a new email event).

originalPayload

Record<string, unknown>

The raw unmodified payload from the upstream service.

metadata

object

Event metadata including triggerSlug, toolkitSlug, triggerConfig, and connectedAccount details.

Show metadata.connectedAccount fields

string

Connected account ID.

uuid

string

Connected account UUID.

authConfigId

string

Auth config ID used for this connection.

userId

string

User ID who owns the connection.

status

"ACTIVE" | "INACTIVE"

Connection status at time of event.

triggers.unsubscribe()

Disconnect from the real-time event stream. Call this during cleanup to release the WebSocket connection.

composio.triggers.unsubscribe(): Promise<void>

triggers.create()

Create (or upsert) a trigger instance for a user. If no connected account ID is provided, the first active connected account for the user and toolkit is used.

composio.triggers.create(
  userId: string,
  slug: string,
  body?: TriggerInstanceUpsertParams
): Promise<TriggerInstanceUpsertResponse>

userId

string

required

External user ID.

slug

string

required

Trigger type slug (e.g. 'GMAIL_NEW_EMAIL').

body.connectedAccountId

string

Specific connected account to attach this trigger to.

body.triggerConfig

Record<string, unknown>

Trigger-specific configuration (e.g. label filter for Gmail, event type for GitHub).

TriggerInstanceUpsertResponse

triggerId

string

ID of the created or updated trigger instance.

triggers.listActive()

List all active trigger instances with optional filtering.

composio.triggers.listActive(
  query?: TriggerInstanceListActiveParams
): Promise<TriggerInstanceListActiveResponse>

query.connectedAccountIds

string[]

Filter by connected account IDs.

query.authConfigIds

string[]

Filter by auth config IDs.

query.triggerIds

string[]

Filter by trigger instance IDs.

query.triggerNames

string[]

Filter by trigger type slugs.

query.showDisabled

boolean

Include disabled trigger instances. Defaults to false.

query.cursor

string

Pagination cursor.

query.limit

number

Maximum items per page.

triggers.listTypes()

List available trigger types, optionally filtered by toolkit.

composio.triggers.listTypes(
  query?: TriggersTypeListParams
): Promise<TriggersTypeListResponse>

query.toolkits

string[]

Filter to specific toolkit slugs.

query.cursor

string

Pagination cursor.

query.limit

number

Maximum items per page.

triggers.getType()

Retrieve a specific trigger type by its slug.

composio.triggers.getType(slug: string): Promise<TriggersTypeRetrieveResponse>

triggers.update()

Update an existing trigger instance’s configuration.

composio.triggers.update(
  triggerId: string,
  body: TriggerInstanceManageUpdateParams
): Promise<TriggerInstanceManageUpdateResponse>

triggerId

string

required

ID of the trigger instance to update.

body

TriggerInstanceManageUpdateParams

required

Fields to update on the trigger instance (e.g. triggerConfig, status).

triggers.delete()

Delete a trigger instance.

composio.triggers.delete(triggerId: string): Promise<TriggerInstanceManageDeleteResponse>

triggers.enable() / disable()

Enable or disable a trigger instance without deleting it.

composio.triggers.enable(triggerId: string): Promise<TriggerInstanceManageUpdateResponse>
composio.triggers.disable(triggerId: string): Promise<TriggerInstanceManageUpdateResponse>

triggers.verifyWebhook()

Verify and parse an incoming webhook payload. Validates the HMAC-SHA256 signature and checks the timestamp is within tolerance.

composio.triggers.verifyWebhook(params: VerifyWebhookParams): Promise<VerifyWebhookResult>

params.payload

string

required

Raw request body as a string. Do not JSON-parse before passing.

params.signature

string

required

Value of the webhook-signature HTTP header.

params.secret

string

required

Webhook secret from the Composio dashboard.

params.id

string

required

Value of the webhook-id HTTP header.

params.timestamp

string

required

Value of the webhook-timestamp HTTP header (Unix seconds).

params.tolerance

number

Maximum allowed webhook age in seconds. Defaults to 300 (5 minutes). Pass 0 to disable timestamp validation.

VerifyWebhookResult

version

"V1" | "V2" | "V3"

Detected webhook payload format version.

payload

IncomingTriggerPayload

Normalized trigger payload.

rawPayload

WebhookPayload

Raw parsed payload before normalization.

Examples

Subscribe to Gmail new email
Subscribe to GitHub events
Verify a webhook
List active triggers

import { Composio } from '@composio/core';

const composio = new Composio();

// First, create a trigger instance for the user
const { triggerId } = await composio.triggers.create(
  'user_123',
  'GMAIL_NEW_EMAIL',
  {
    triggerConfig: {
      userId: 'me',
      interval: 60, // poll every 60 seconds
      labelIds: ['INBOX'],
    },
  }
);

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

// Subscribe to real-time events
await composio.triggers.subscribe(
  (event) => {
    console.log('New email from:', event.payload.from);
    console.log('Subject:', event.payload.subject);
    console.log('User:', event.userId);
  },
  {
    triggerSlug: ['GMAIL_NEW_EMAIL'],
    userId: 'user_123',
  }
);

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

import { Composio } from '@composio/core';

const composio = new Composio();

// Create a trigger instance
await composio.triggers.create('user_123', 'GITHUB_PULL_REQUEST_EVENT');

// Subscribe to all GitHub events for any user
await composio.triggers.subscribe(
  (event) => {
    if (event.triggerSlug === 'GITHUB_PULL_REQUEST_EVENT') {
      const pr = event.payload;
      console.log(`PR #${pr.number}: ${pr.title} — ${pr.action}`);
    }
  },
  { toolkits: ['github'] }
);

import { Composio } from '@composio/core';
import express from 'express';

const app = express();
const composio = new Composio();

app.post('/webhooks/composio', express.raw({ type: '*/*' }), 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('Verified trigger:', result.payload.triggerSlug);
    console.log('Webhook version:', result.version);

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

import { Composio } from '@composio/core';

const composio = new Composio();

const { items } = await composio.triggers.listActive({
  showDisabled: false,
  limit: 50,
});

items.forEach(trigger => {
  console.log(`${trigger.triggerName}: ${trigger.id}`);
  console.log(`  Connected account: ${trigger.connectedAccountId}`);
  console.log(`  Updated: ${trigger.updatedAt}`);
});

TypeScript SDK

Python SDK

REST API

Triggers API — Composio TypeScript SDK Reference

IncomingTriggerPayload

triggers.unsubscribe()

triggers.create()

TriggerInstanceUpsertResponse

triggers.listActive()

triggers.listTypes()

triggers.getType()

triggers.update()

triggers.delete()

triggers.enable() / disable()

triggers.verifyWebhook()

VerifyWebhookResult

Examples

Build docs developers (and LLMs) love

TypeScript SDK

Python SDK

REST API

Documentation Index

​triggers.subscribe()

​IncomingTriggerPayload

​triggers.unsubscribe()

​triggers.create()

​TriggerInstanceUpsertResponse

​triggers.listActive()

​triggers.listTypes()

​triggers.getType()

​triggers.update()

​triggers.delete()

​triggers.enable() / disable()

​triggers.verifyWebhook()

​VerifyWebhookResult

​Examples

Build docs developers (and LLMs) love

triggers.subscribe()

IncomingTriggerPayload

triggers.unsubscribe()

triggers.create()

TriggerInstanceUpsertResponse

triggers.listActive()

triggers.listTypes()

triggers.getType()

triggers.update()

triggers.delete()

triggers.enable() / disable()

triggers.verifyWebhook()

VerifyWebhookResult

Examples