Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
import ComposioClient, { APIError } from '@composio/client';
import {
TriggersTypeRetrieveEnumResponse,
type TriggerInstanceUpsertParams as ClientTriggerInstanceUpsertParams,
} from '@composio/client/resources/index';
import {
TriggerInstanceUpsertResponse,
TriggerInstanceUpsertParamsSchema,
TriggerInstanceUpsertParams,
TriggerInstanceListActiveParams,
TriggerInstanceListActiveParamsSchema,
TriggerInstanceListActiveResponse,
TriggerSubscribeParams,
TriggerInstanceManageUpdateParams,
TriggerInstanceManageUpdateResponse,
TriggerInstanceManageDeleteResponse,
TriggerSubscribeParamSchema,
IncomingTriggerPayload,
TriggerData,
TriggersTypeListParams,
TriggersTypeListResponse,
TriggersTypeListParamsSchema,
TriggersTypeRetrieveResponse,
VerifyWebhookParams,
VerifyWebhookParamsSchema,
VerifyWebhookResult,
ParseWebhookOptions,
WebhookRequestLike,
WebhookPayload,
WebhookPayloadV1Schema,
WebhookPayloadV2Schema,
WebhookPayloadV3Schema,
WebhookTriggerPayloadV3Schema,
WebhookVersion,
WebhookVersions,
SetWebhookSubscriptionParams,
WebhookSubscription,
} from '../types/triggers.types';
import { upsertWebhookSubscription } from './Webhooks';
import logger from '../utils/logger';
import { telemetry } from '../telemetry/Telemetry';
import { ValidationError } from '../errors';
import { PusherService } from '../services/pusher/Pusher';
import {
ComposioTriggerTypeNotFoundError,
ComposioWebhookPayloadError,
ComposioWebhookSignatureVerificationError,
} from '../errors/TriggerErrors';
import { transform } from '../utils/transform';
import {
transformIncomingTriggerPayload,
transformTriggerInstanceListActiveResponse,
transformTriggerTypeListResponse,
transformTriggerTypeRetrieveResponse,
} from '../utils/transformers/triggers';
import { ToolkitVersionParam } from '../types/tool.types';
import type { ComposioConfig } from '../composio';
import type { BaseComposioProvider } from '../provider/BaseProvider';
import { hmacSha256Base64, timingSafeEqual } from '../utils/crypto';
import { CONFIG_DEFAULTS } from '../utils/config-defaults';
import { ComposioRequestOptions } from '../types/requestOptions.types';
import { withCancellation } from '../utils/cancellation';
/**
* Safely converts a value to a string, returning the default if the value is null, undefined, or empty.
* This prevents runtime crashes when calling string methods like `.toLowerCase()` on non-string values.
* @private
*/
const toStringOrDefault = (value: unknown, defaultValue: string): string => {
if (value === null || value === undefined) {
return defaultValue;
}
const str = String(value);
return str.length > 0 ? str : defaultValue;
};
/**
* The signature header names Composio sends with every webhook delivery.
* @private
*/
const WEBHOOK_HEADERS = {
id: 'webhook-id',
timestamp: 'webhook-timestamp',
signature: 'webhook-signature',
} as const;
/**
* Returns true if the value is a Fetch API `Request`.
* @private
*/
const isFetchRequest = (request: WebhookRequestLike): request is Request =>
typeof Request !== 'undefined' && request instanceof Request;
/**
* Reads a single header value case-insensitively from either a `Headers`
* instance or a plain record (where values may be `string | string[]`).
* Returns `undefined` when the header is missing.
* @private
*/
const getHeader = (headers: unknown, name: string): string | undefined => {
if (typeof Headers !== 'undefined' && headers instanceof Headers) {
return headers.get(name) ?? undefined;
}
if (headers === null || typeof headers !== 'object') {
return undefined;
}
// Plain record: match the header name case-insensitively.
const target = name.toLowerCase();
for (const [key, value] of Object.entries(headers as Record<string, unknown>)) {
if (key.toLowerCase() !== target) {
continue;
}
if (Array.isArray(value)) {
const first = value.find((item): item is string => typeof item === 'string');
return first;
}
return typeof value === 'string' ? value : undefined;
}
return undefined;
};
/**
* Coerces an object request body (string, Buffer/Uint8Array, or already-parsed
* value) into the raw string form expected by signature verification.
* @private
*/
const bodyToString = (body: unknown): string => {
if (typeof body === 'string') {
return body;
}
if (body instanceof Uint8Array) {
return new TextDecoder().decode(body);
}
if (body === null || body === undefined) {
return '';
}
// Already-parsed object (e.g. Next.js Pages Router with the JSON body parser).
// Note: re-stringifying cannot reproduce the exact bytes Composio signed, so
// signature verification on a pre-parsed body is best-effort only.
if (typeof body === 'object') {
return JSON.stringify(body);
}
return String(body);
};
/**
* Trigger (Instance) class
* /api/v3/trigger_instances
*
*/
export class Triggers<TProvider extends BaseComposioProvider<unknown, unknown, unknown>> {
private client: ComposioClient;
private pusherService: PusherService;
private toolkitVersions: ToolkitVersionParam;
constructor(client: ComposioClient, config?: ComposioConfig<TProvider>) {
this.client = client;
this.pusherService = new PusherService(client);
this.toolkitVersions = config?.toolkitVersions ?? CONFIG_DEFAULTS.toolkitVersions;
telemetry.instrument(this, 'Triggers');
}
/**
* Create or update the project webhook subscription used for webhook delivery.
*
* If a subscription already exists, the first subscription is updated. Otherwise a new
* subscription is created. By default this subscribes to V3 trigger message events.
*
* @example
* ```ts
* await composio.triggers.setWebhookSubscription({
* webhookUrl: `${APP_URL}/webhooks/composio`,
* });
* ```
*/
async setWebhookSubscription(params: SetWebhookSubscriptionParams): Promise<WebhookSubscription> {
return upsertWebhookSubscription(this.client, params);
}
/**
* Fetch list of all the active triggers
*
* @param {TriggerInstanceListActiveParams} query - The query parameters to filter the trigger instances
* @returns {Promise<TriggerInstanceListActiveResponse>} List of trigger instances
*
* @throws {ValidationError} If the parameters are invalid
* @throws {Error} If the client is not authenticated
*
* @example
* ```ts
* const triggers = await triggers.listActive({
* authConfigIds: ['123'],
* connectedAccountIds: ['456'],
* });
* ```
*/
async listActive(
query?: TriggerInstanceListActiveParams,
requestOptions?: ComposioRequestOptions
): Promise<TriggerInstanceListActiveResponse> {
// Validate the parameters if provided
const parsedParams = TriggerInstanceListActiveParamsSchema.safeParse(query ?? {});
if (!parsedParams.success) {
throw new ValidationError(`Invalid parameters passed to list triggers`, {
cause: parsedParams.error,
});
}
const listParams = query
? {
auth_config_ids: parsedParams.data.authConfigIds,
connected_account_ids: parsedParams.data.connectedAccountIds,
cursor: parsedParams.data.cursor,
limit: parsedParams.data.limit,
show_disabled: parsedParams.data.showDisabled,
trigger_ids: parsedParams.data.triggerIds,
trigger_names: parsedParams.data.triggerNames,
}
: undefined;
const result = await withCancellation(
() => this.client.triggerInstances.listActive(listParams, requestOptions),
requestOptions?.signal
);
return transformTriggerInstanceListActiveResponse(result);
}
/**
* Create a new trigger instance for a user
* If the connected account id is not provided, the first connected account for the user and toolkit will be used
*
* @param {string} userId - The user id of the trigger instance
* @param {string} slug - The slug of the trigger instance
* @param {TriggerInstanceUpsertParams} body - The parameters to create the trigger instance
* @returns {Promise<TriggerInstanceUpsertResponse>} The created trigger instance
*/
async create(
userId: string,
slug: string,
body?: TriggerInstanceUpsertParams,
requestOptions?: ComposioRequestOptions
): Promise<TriggerInstanceUpsertResponse> {
if (!userId?.trim()) {
throw new ValidationError(`A non-empty userId is required to create a trigger`);
}
const parsedBody = TriggerInstanceUpsertParamsSchema.safeParse(body ?? {});
if (!parsedBody.success) {
throw new ValidationError(`Invalid parameters passed to create trigger`, {
cause: parsedBody.error,
});
}
// Validate the trigger slug up-front so callers get a clear client-side
// `ComposioTriggerTypeNotFoundError`. The Python SDK mirrors this behavior.
try {
await this.getType(slug, requestOptions);
} catch (error) {
// The trigger types endpoint returns 400 (not 404) for an unknown slug.
if (error instanceof APIError && (error.status === 400 || error.status === 404)) {
throw new ComposioTriggerTypeNotFoundError(`Trigger type ${slug} not found`, {
cause: error,
possibleFixes: [
`Please check the trigger slug`,
`Please check the provided version of toolkit has the trigger`,
`Visit the toolkit page to see the available triggers`,
],
});
}
throw error;
}
// Pass `user_id` straight through: when `connected_account_id` is omitted the
// backend resolves the first active connection for this user and the
// trigger's toolkit, mirroring tool execution. When 2FA is enabled and
// `connected_account_id` is pinned, the backend validates that `user_id`
// owns it.
const upsertParams: ClientTriggerInstanceUpsertParams = {
connected_account_id: parsedBody.data.connectedAccountId,
trigger_config: parsedBody.data.triggerConfig,
toolkit_versions: this.toolkitVersions,
user_id: userId,
};
const result = await withCancellation(
() => this.client.triggerInstances.upsert(slug, upsertParams, requestOptions),
requestOptions?.signal
);
return {
triggerId: result.trigger_id,
};
}
/**
* Update an existing trigger instance
*
* @param {string} triggerId - The Id of the trigger instance
* @param {TriggerInstanceManageUpdateParams} body - The parameters to update the trigger instance
* @returns {Promise<TriggerInstanceManageUpdateResponse>} The updated trigger instance response
*/
async update(
triggerId: string,
body: TriggerInstanceManageUpdateParams,
requestOptions?: ComposioRequestOptions
): Promise<TriggerInstanceManageUpdateResponse> {
return withCancellation(
() => this.client.triggerInstances.manage.update(triggerId, body, requestOptions),
requestOptions?.signal
);
}
/**
* Delete a trigger instance
*
* @param {string} triggerId - The slug of the trigger instance
* @returns
*/
async delete(
triggerId: string,
requestOptions?: ComposioRequestOptions
): Promise<TriggerInstanceManageDeleteResponse> {
const result = await withCancellation(
() => this.client.triggerInstances.manage.delete(triggerId, requestOptions),
requestOptions?.signal
);
return {
triggerId: result.trigger_id,
};
}
/**
* Disable a trigger instance
*
* @param {string} triggerId - The id of the trigger instance
* @returns {Promise<TriggerInstanceUpsertResponse>} The updated trigger instance
*/
async disable(triggerId: string, requestOptions?: ComposioRequestOptions) {
const body = { status: 'disable' as const };
return withCancellation(
() => this.client.triggerInstances.manage.update(triggerId, body, requestOptions),
requestOptions?.signal
);
}
/**
* Enable a trigger instance
*
* @param {string} triggerId - The id of the trigger instance
* @returns {Promise<TriggerInstanceUpsertResponse>} The updated trigger instance
*/
async enable(triggerId: string, requestOptions?: ComposioRequestOptions) {
const body = { status: 'enable' as const };
return withCancellation(
() => this.client.triggerInstances.manage.update(triggerId, body, requestOptions),
requestOptions?.signal
);
}
/**
* @TODO Learn about trigger types
*/
/**
* List all the trigger types
*
* @param {TriggersTypeListParams} query - The query parameters to filter the trigger types
* @param {RequestOptions} options - Request options
* @returns {Promise<TriggersTypeListResponse>} The list of trigger types
*/
async listTypes(
query?: TriggersTypeListParams,
requestOptions?: ComposioRequestOptions
): Promise<TriggersTypeListResponse> {
const parsedQuery = transform(query ?? {})
.with(TriggersTypeListParamsSchema)
.using(raw => raw);
const listParams = {
cursor: parsedQuery.cursor,
limit: parsedQuery.limit,
toolkit_slugs: parsedQuery.toolkits,
toolkit_versions: this.toolkitVersions,
};
const result = await withCancellation(
() => this.client.triggersTypes.list(listParams, requestOptions),
requestOptions?.signal
);
return transformTriggerTypeListResponse(result);
}
/**
* Retrieve a trigger type by its slug for the provided version of the app
* Use the global toolkit versions param when initializing composio to pass a toolkitversion
*
* @param {string} slug - The slug of the trigger type
* @returns {Promise<TriggersTypeRetrieveResponse>} The trigger type object
*/
async getType(
slug: string,
requestOptions?: ComposioRequestOptions
): Promise<TriggersTypeRetrieveResponse> {
const retrieveParams = {
// if the version is provided override the global version
toolkit_versions: this.toolkitVersions,
};
const result = await withCancellation(
() => this.client.triggersTypes.retrieve(slug, retrieveParams, requestOptions),
requestOptions?.signal
);
return transformTriggerTypeRetrieveResponse(result);
}
/**
* Fetches the list of all the available trigger enums
*
* This method is used by the CLI where filters are not required.
* @returns
*/
async listEnum(
requestOptions?: ComposioRequestOptions
): Promise<TriggersTypeRetrieveEnumResponse> {
return withCancellation(
() => this.client.triggersTypes.retrieveEnum(requestOptions),
requestOptions?.signal
);
}
/**
* Applies compound filters to the trigger data
* @param data data to apply filters to
* @returns True if the trigger data matches the filters, false otherwise
*/
private shouldSendTriggerAfterFilters(
filters: TriggerSubscribeParams,
data: IncomingTriggerPayload
): boolean {
// Check if toolkits filter is provided and matches
if (
filters.toolkits?.length &&
!filters.toolkits
.map(toolkit => toolkit.toLowerCase())
.includes(data.toolkitSlug.toLowerCase())
) {
logger.debug(
'Trigger does not match toolkits filter',
JSON.stringify(filters.toolkits, null, 2)
);
return false;
}
// Check if triggerId filter matches
if (filters.triggerId && filters.triggerId !== data.id) {
logger.debug(
'Trigger does not match triggerId filter',
JSON.stringify(filters.triggerId, null, 2)
);
return false;
}
// Check if connectedAccountId filter matches
if (
filters.connectedAccountId &&
filters.connectedAccountId !== data.metadata.connectedAccount.id
) {
logger.debug(
'Trigger does not match connectedAccountId filter',
JSON.stringify(filters.connectedAccountId, null, 2)
);
return false;
}
// Check if authConfigId filter matches.
// Only V3 trigger payloads (and the legacy TriggerData shape) carry an auth config id;
// V1/V2 payloads and non-trigger V3 events normalize it to '', so this filter drops
// those events entirely. This mirrors the Python SDK's `auth_config_id` filter.
if (
filters.authConfigId &&
filters.authConfigId !== data.metadata.connectedAccount.authConfigId
) {
logger.debug(
'Trigger does not match authConfigId filter',
JSON.stringify(filters.authConfigId, null, 2)
);
return false;
}
// Check if triggerName filter matches
if (
filters.triggerSlug?.length &&
!filters.triggerSlug
.map(triggerSlug => triggerSlug.toLowerCase())
.includes(data.triggerSlug.toLowerCase())
) {
logger.debug(
'Trigger does not match triggerSlug filter',
JSON.stringify(filters.triggerSlug, null, 2)
);
return false;
}
// Check if triggerData filter matches
if (filters.triggerData && filters.triggerData !== data.metadata.triggerData) {
logger.debug(
'Trigger does not match triggerData filter',
JSON.stringify(filters.triggerData, null, 2)
);
return false;
}
// Check if userId (clientUniqueUserId) filter matches
if (filters.userId && filters.userId !== data.metadata.connectedAccount.userId) {
logger.debug('Trigger does not match userId filter', JSON.stringify(filters.userId, null, 2));
return false;
}
logger.debug('Trigger matches all filters', JSON.stringify(filters, null, 2));
// If all filters pass or no filters were provided, return true
return true;
}
/**
* Subscribe to all the triggers
*
* @param fn - The function to call when a trigger is received
* @param filters - The filters to apply to the triggers
*
* @example
* ```ts
*
* triggers.subscribe((data) => {
* console.log(data);
* }, );
* ```
*/
async subscribe(
fn: (_data: IncomingTriggerPayload) => void,
filters: TriggerSubscribeParams = {}
) {
if (!fn) throw new Error('Function is required for trigger subscription');
const parsedFilters = TriggerSubscribeParamSchema.safeParse(filters);
if (!parsedFilters.success) {
throw new ValidationError(`Invalid parameters passed to subscribe to triggers`, {
cause: parsedFilters.error,
});
}
logger.debug('🔄 Subscribing to triggers with filters: ', JSON.stringify(filters, null, 2));
await this.pusherService.subscribe((_data: Record<string, unknown>) => {
logger.debug('Received raw trigger data', JSON.stringify(_data, null, 2));
// Parse using unified method that handles V1/V2/V3 and legacy formats
const parsedData = this.parsePusherPayload(_data);
if (this.shouldSendTriggerAfterFilters(parsedFilters.data, parsedData)) {
try {
fn(parsedData);
} catch (error) {
logger.error('❌ Error in trigger callback:', error);
}
} else {
logger.debug('Trigger does not match filters', JSON.stringify(parsedFilters.data, null, 2));
}
});
}
/**
* Tries to parse data as V1, V2, or V3 webhook payload format.
* Returns the parsed result with version info, or null if no format matches.
* Also returns any schema validation errors for debugging purposes.
* @private
*/
private tryParseVersionedPayload(data: unknown):
| {
ok: true;
version: WebhookVersion;
rawPayload: WebhookPayload;
normalizedPayload: IncomingTriggerPayload;
}
| {
ok: false;
v1Error: string;
v2Error: string;
v3Error: string;
} {
// Try V3 first (has 'composio.trigger.message' type)
const v3Result = WebhookPayloadV3Schema.safeParse(data);
if (v3Result.success) {
return {
ok: true,
version: WebhookVersions.V3,
rawPayload: v3Result.data,
normalizedPayload: this.normalizeV3Payload(v3Result.data),
};
}
// Try V2 (has 'type', 'timestamp', 'log_id', and 'data')
const v2Result = WebhookPayloadV2Schema.safeParse(data);
if (v2Result.success) {
return {
ok: true,
version: WebhookVersions.V2,
rawPayload: v2Result.data,
normalizedPayload: this.normalizeV2Payload(v2Result.data),
};
}
// Try V1 (has 'trigger_name', 'connection_id', 'trigger_id', 'payload', 'log_id')
const v1Result = WebhookPayloadV1Schema.safeParse(data);
if (v1Result.success) {
return {
ok: true,
version: WebhookVersions.V1,
rawPayload: v1Result.data,
normalizedPayload: this.normalizeV1Payload(v1Result.data),
};
}
return {
ok: false,
v1Error: v1Result.error.message,
v2Error: v2Result.error.message,
v3Error: v3Result.error.message,
};
}
/**
* Parses incoming Pusher payload, supporting V1, V2, V3, and legacy TriggerData formats.
* @private
*/
private parsePusherPayload(data: Record<string, unknown>): IncomingTriggerPayload {
// Try V1/V2/V3 formats
const versionedResult = this.tryParseVersionedPayload(data);
if (versionedResult.ok) {
logger.debug(`Parsed Pusher payload as ${versionedResult.version} format`);
return versionedResult.normalizedPayload;
}
// Try legacy TriggerData format (for backwards compatibility)
const legacyData = data as TriggerData;
if (legacyData.metadata?.nanoId && legacyData.appName) {
logger.debug('Parsed Pusher payload as legacy TriggerData format');
return transformIncomingTriggerPayload(legacyData);
}
// Fallback: log warning and return a minimal payload with available data
logger.warn('Unknown Pusher payload format. Payload keys: ' + Object.keys(data).join(', '));
// Return a minimal payload structure to avoid breaking the subscription
// Use toStringOrDefault to safely convert values and prevent crashes when
// non-string values are passed (e.g., numbers, objects) and .toLowerCase() is called later
const id = toStringOrDefault(data.id, toStringOrDefault(data.trigger_id, 'unknown'));
const uuid = toStringOrDefault(data.uuid, toStringOrDefault(data.id, 'unknown'));
const triggerSlug = toStringOrDefault(
data.triggerSlug,
toStringOrDefault(data.trigger_name, 'UNKNOWN')
);
const toolkitSlug = toStringOrDefault(
data.toolkitSlug,
toStringOrDefault(data.appName, 'UNKNOWN')
);
const userId = toStringOrDefault(data.userId, '');
return {
id,
uuid,
triggerSlug,
toolkitSlug,
userId,
payload: (data.payload as Record<string, unknown>) || data,
originalPayload: (data.originalPayload as Record<string, unknown>) || data,
metadata: {
id,
uuid,
triggerSlug,
toolkitSlug,
triggerConfig: {},
connectedAccount: {
id: '',
uuid: '',
authConfigId: '',
authConfigUUID: '',
userId: '',
status: 'ACTIVE',
},
},
};
}
/**
* Unsubscribe from all the triggers
*
* @returns {Promise<void>}
*
* @example
* ```ts
* composio.trigger.subscribe((data) => {
* console.log(data);
* });
*
* await triggers.unsubscribe();
* ```
*/
async unsubscribe() {
await this.pusherService.unsubscribe();
}
/**
* Parse an incoming webhook HTTP request into a typed, normalized trigger payload.
*
* Dump the incoming request in and get back the parsed Composio trigger event.
* When `verifySecret` is provided, the request signature is verified before the
* payload is returned (delegating to {@link verifyWebhook}); without it, the body
* is parsed without verification.
*
* The `request` may be either a Fetch API `Request` (Next.js App Router, Hono,
* Remix) or a plain `{ body, headers }` object (Express with `express.raw`,
* Next.js Pages Router `req`). The signature headers (`webhook-id`,
* `webhook-timestamp`, `webhook-signature`) are read case-insensitively.
*
* @param {WebhookRequestLike} request - The incoming webhook HTTP request
* @param {ParseWebhookOptions} [options] - Parse options
* @param {string} [options.verifySecret] - Webhook secret; when set, the signature is verified
* @param {number} [options.tolerance=300] - Max webhook age in seconds (only used when verifying)
* @returns {Promise<VerifyWebhookResult>} The parsed (and optionally verified) webhook payload
*
* @throws {ValidationError} If `verifySecret` is set but the signature headers are missing
* @throws {ComposioWebhookSignatureVerificationError} If signature verification fails
* @throws {ComposioWebhookPayloadError} If the payload cannot be parsed
*
* @example
* ```ts
* // Express with express.raw (verify the signature)
* app.post('/webhooks/composio', express.raw({ type: 'application/json' }), async (req, res) => {
* try {
* const result = await composio.triggers.parse(req, {
* verifySecret: process.env.COMPOSIO_WEBHOOK_SECRET,
* });
* console.log('Trigger:', result.payload.triggerSlug);
* console.log('Event data:', result.payload.payload);
* res.sendStatus(200);
* } catch (error) {
* res.sendStatus(401);
* }
* });
*
* // Express without verifying (parse only)
* app.post('/webhooks/composio', express.raw({ type: 'application/json' }), async (req, res) => {
* const result = await composio.triggers.parse(req);
* console.log('Trigger:', result.payload.triggerSlug);
* res.sendStatus(200);
* });
* ```
*
* @example
* ```ts
* // Next.js App Router (Request) — verify the signature
* export async function POST(request: Request) {
* try {
* const result = await composio.triggers.parse(request, {
* verifySecret: process.env.COMPOSIO_WEBHOOK_SECRET,
* });
* console.log('Trigger:', result.payload.triggerSlug);
* console.log('Event data:', result.payload.payload);
* return new Response('OK', { status: 200 });
* } catch (error) {
* return new Response('Unauthorized', { status: 401 });
* }
* }
*
* // Next.js App Router — parse only (no verification)
* export async function POST(request: Request) {
* const result = await composio.triggers.parse(request);
* console.log('Trigger:', result.payload.triggerSlug);
* return new Response('OK', { status: 200 });
* }
* ```
*/
async parse(
request: WebhookRequestLike,
options?: ParseWebhookOptions
): Promise<VerifyWebhookResult> {
// Extract the raw body and signature headers from either request shape.
let body: string;
let headers: unknown;
if (isFetchRequest(request)) {
body = await request.text();
headers = request.headers;
} else {
body = bodyToString(request.body);
headers = request.headers;
}
const verifySecret = options?.verifySecret;
// Distinguish "caller omitted verifySecret" (explicit opt-out) from
// "caller passed verifySecret but it resolved to empty" (almost always an
// unset COMPOSIO_WEBHOOK_SECRET). The latter must fail loudly rather than
// silently skip verification and accept forged events.
const optedOutOfVerification = options === undefined || !('verifySecret' in options);
if (optedOutOfVerification) {
// No secret requested: parse without verifying the signature.
const { version, rawPayload, normalizedPayload } = this.parseWebhookPayload(body);
return {
version,
payload: normalizedPayload,
rawPayload,
};
}
if (!verifySecret) {
throw new ValidationError(
`Cannot verify webhook: 'verifySecret' was provided but is empty — your ` +
`COMPOSIO_WEBHOOK_SECRET is likely unset. Set the secret, or omit 'verifySecret' ` +
`entirely to parse without verification.`
);
}
// Secret provided: signature headers are required to verify.
const id = getHeader(headers, WEBHOOK_HEADERS.id);
const timestamp = getHeader(headers, WEBHOOK_HEADERS.timestamp);
const signature = getHeader(headers, WEBHOOK_HEADERS.signature);
if (!id || !timestamp || !signature) {
const missing = [
!id ? `'${WEBHOOK_HEADERS.id}'` : undefined,
!timestamp ? `'${WEBHOOK_HEADERS.timestamp}'` : undefined,
!signature ? `'${WEBHOOK_HEADERS.signature}'` : undefined,
].filter((header): header is string => header !== undefined);
throw new ValidationError(
`Cannot verify webhook: missing signature header(s) ${missing.join(', ')}. ` +
`Pass the raw, unparsed request body and ensure the Composio signature headers ` +
`(${WEBHOOK_HEADERS.id}, ${WEBHOOK_HEADERS.timestamp}, ${WEBHOOK_HEADERS.signature}) ` +
`are forwarded to triggers.parse(). To parse without verifying, omit 'verifySecret'.`
);
}
return this.verifyWebhook({
payload: body,
signature,
id,
timestamp,
secret: verifySecret,
tolerance: options?.tolerance,
});
}
/**
* Verify an incoming webhook payload and signature.
*
* This method validates that the webhook request is authentic by:
* 1. Verifying the HMAC-SHA256 signature matches the payload using the correct signing format
* 2. Optionally checking that the webhook timestamp is within the tolerance window
*
* The signature is computed as: `HMAC-SHA256(${webhookId}.${webhookTimestamp}.${payload}, secret)`
* and is expected in the format: `v1,base64EncodedSignature`
*
* @param {VerifyWebhookParams} params - The verification parameters
* @param {string} params.payload - The raw webhook payload as a string (request body)
* @param {string} params.signature - The signature from the 'webhook-signature' header
* @param {string} params.secret - The webhook secret used to sign the payload
* @param {string} params.webhookId - The webhook ID from the 'webhook-id' header
* @param {string} params.webhookTimestamp - The timestamp from the 'webhook-timestamp' header (Unix seconds)
* @param {number} [params.tolerance=300] - Maximum allowed age of the webhook in seconds (default: 5 minutes). Set to 0 to disable timestamp validation.
* @returns {VerifyWebhookResult} The verified and parsed webhook payload with version information
*
* @throws {ValidationError} If the parameters are invalid
* @throws {ComposioWebhookSignatureVerificationError} If the signature verification fails
* @throws {ComposioWebhookPayloadError} If the payload cannot be parsed or is invalid
*
* @example
* ```ts
* // In an Express.js webhook handler
* 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,
* webhookId: req.headers['webhook-id'] as string,
* webhookTimestamp: req.headers['webhook-timestamp'] as string,
* secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
* });
*
* // Process the verified payload
* console.log('Webhook version:', result.version);
* console.log('Received trigger:', result.payload.triggerSlug);
* res.status(200).send('OK');
* } catch (error) {
* console.error('Webhook verification failed:', error);
* res.status(401).send('Unauthorized');
* }
* });
* ```
*/
async verifyWebhook(params: VerifyWebhookParams): Promise<VerifyWebhookResult> {
// Validate input parameters
const parsedParams = VerifyWebhookParamsSchema.safeParse(params);
if (!parsedParams.success) {
// Extract missing required parameters for a more helpful error message
const missingParams = parsedParams.error.issues
.filter(issue => issue.code === 'invalid_type' && issue.received === 'undefined')
.map(issue => {
const paramName = issue.path[0] as string;
const headerMap: Record<string, string> = {
id: 'webhook-id',
timestamp: 'webhook-timestamp',
signature: 'webhook-signature',
};
const headerName = headerMap[paramName];
return headerName ? `'${paramName}' (from '${headerName}' header)` : `'${paramName}'`;
});
if (missingParams.length > 0) {
throw new ValidationError(
`Missing required parameters: ${missingParams.join(', ')}. ` +
`Extract these values from the HTTP request headers and body.`,
{ cause: parsedParams.error }
);
}
throw new ValidationError('Invalid parameters passed to verifyWebhook', {
cause: parsedParams.error,
});
}
const {
payload,
signature,
secret,
id: webhookId,
timestamp: webhookTimestamp,
tolerance,
} = parsedParams.data;
// Validate timestamp if tolerance is set
if (tolerance > 0) {
this.validateWebhookTimestamp(webhookTimestamp, tolerance);
}
// Verify signature using the correct format: msgId.timestamp.payload
await this.verifyWebhookSignature(webhookId, webhookTimestamp, payload, signature, secret);
// Parse the payload and detect version
const { version, rawPayload, normalizedPayload } = this.parseWebhookPayload(payload);
return {
version,
payload: normalizedPayload,
rawPayload,
};
}
/**
* Parses the webhook payload and detects its version (V1, V2, or V3)
* @private
*/
private parseWebhookPayload(payload: string): {
version: WebhookVersion;
rawPayload: WebhookPayload;
normalizedPayload: IncomingTriggerPayload;
} {
let jsonPayload: unknown;
try {
jsonPayload = JSON.parse(payload);
} catch (error) {
throw new ComposioWebhookPayloadError('Failed to parse webhook payload as JSON', {
cause: error,
});
}
// Try V1/V2/V3 formats using shared parsing logic
const result = this.tryParseVersionedPayload(jsonPayload);
if (result.ok) {
const { ok, ...rest } = result;
return rest;
}
const { v1Error, v2Error, v3Error } = result;
// None of the schemas matched
throw new ComposioWebhookPayloadError(
'Webhook payload does not match any known version (V1, V2, or V3). ' +
'Please ensure you are using a supported webhook payload format.',
{
cause: {
v1Error,
v2Error,
v3Error,
},
}
);
}
/**
* Normalizes a V1 webhook payload to IncomingTriggerPayload format
* @private
*/
private normalizeV1Payload(
payload: import('../types/triggers.types').WebhookPayloadV1
): IncomingTriggerPayload {
// V1 has limited information, so we use what's available
// and mark unknown fields appropriately
const triggerName = payload.trigger_name;
const toolkitSlug = triggerName.split('_')[0]?.toUpperCase() || 'UNKNOWN';
return {
id: payload.trigger_id,
uuid: payload.trigger_id, // V1 doesn't have UUID, use trigger_id
triggerSlug: triggerName,
toolkitSlug,
userId: '', // V1 doesn't provide userId
payload: payload.payload,
originalPayload: payload.payload,
metadata: {
id: payload.trigger_id,
uuid: payload.trigger_id,
toolkitSlug,
triggerSlug: triggerName,
triggerConfig: {},
connectedAccount: {
id: payload.connection_id,
uuid: payload.connection_id,
authConfigId: '',
authConfigUUID: '',
userId: '',
status: 'ACTIVE',
},
},
};
}
/**
* Normalizes a V2 webhook payload to IncomingTriggerPayload format
* @private
*/
private normalizeV2Payload(
payload: import('../types/triggers.types').WebhookPayloadV2
): IncomingTriggerPayload {
const triggerSlug = payload.type.toUpperCase();
const toolkitSlug = triggerSlug.split('_')[0] || 'UNKNOWN';
// Extract data fields
const { connection_id, connection_nano_id, trigger_nano_id, trigger_id, user_id, ...restData } =
payload.data;
return {
id: trigger_nano_id,
uuid: trigger_id,
triggerSlug,
toolkitSlug,
userId: user_id,
payload: restData,
originalPayload: restData,
metadata: {
id: trigger_nano_id,
uuid: trigger_id,
toolkitSlug,
triggerSlug,
triggerConfig: {},
connectedAccount: {
id: connection_nano_id,
uuid: connection_id,
authConfigId: '',
authConfigUUID: '',
userId: user_id,
status: 'ACTIVE',
},
},
};
}
/**
* Normalizes a V3 webhook payload to IncomingTriggerPayload format
* @private
*/
private normalizeV3Payload(
payload: import('../types/triggers.types').WebhookPayloadV3
): IncomingTriggerPayload {
// Check if this is a trigger event with trigger-specific metadata
const triggerResult = WebhookTriggerPayloadV3Schema.safeParse(payload);
if (triggerResult.success) {
const triggerSlug = triggerResult.data.metadata.trigger_slug;
const toolkitSlug = triggerSlug.split('_')[0]?.toUpperCase() || 'UNKNOWN';
return {
id: triggerResult.data.metadata.trigger_id,
uuid: triggerResult.data.metadata.trigger_id,
triggerSlug,
toolkitSlug,
userId: triggerResult.data.metadata.user_id,
payload: payload.data,
originalPayload: payload.data,
metadata: {
id: triggerResult.data.metadata.trigger_id,
uuid: triggerResult.data.metadata.trigger_id,
toolkitSlug,
triggerSlug,
triggerConfig: {},
connectedAccount: {
id: triggerResult.data.metadata.connected_account_id,
uuid: triggerResult.data.metadata.connected_account_id,
authConfigId: triggerResult.data.metadata.auth_config_id,
authConfigUUID: triggerResult.data.metadata.auth_config_id,
userId: triggerResult.data.metadata.user_id,
status: 'ACTIVE',
},
},
};
}
// Non-trigger V3 event (e.g., connection expired)
// Return a minimal payload; callers should use specific schemas
// (e.g., ConnectionExpiredEventSchema) on rawPayload for type-safe access
return {
id: payload.id,
uuid: payload.id,
triggerSlug: payload.type,
toolkitSlug: 'COMPOSIO',
userId: '',
payload: payload.data,
originalPayload: payload as unknown as Record<string, unknown>,
metadata: {
id: payload.id,
uuid: payload.id,
toolkitSlug: 'COMPOSIO',
triggerSlug: payload.type,
triggerConfig: {},
connectedAccount: {
id: '',
uuid: '',
authConfigId: '',
authConfigUUID: '',
userId: '',
status: 'ACTIVE',
},
},
};
}
/**
* Verifies the HMAC-SHA256 signature of a webhook payload.
* The signature format used by Composio is: `v1,base64EncodedSignature`
* The signing input is: `${msgId}.${timestamp}.${payload}`
* @private
*/
private async verifyWebhookSignature(
webhookId: string,
webhookTimestamp: string,
payload: string,
signature: string,
secret: string
): Promise<void> {
if (payload.length === 0) {
throw new ComposioWebhookSignatureVerificationError('No webhook payload was provided.');
}
if (signature.length === 0) {
throw new ComposioWebhookSignatureVerificationError(
"No signature header value was provided. Please pass the value of the 'webhook-signature' header."
);
}
if (secret.length === 0) {
throw new ComposioWebhookSignatureVerificationError(
'No webhook secret was provided. You can find your webhook secret in your Composio dashboard.'
);
}
if (webhookId.length === 0) {
throw new ComposioWebhookSignatureVerificationError(
"No webhook ID was provided. Please pass the value of the 'webhook-id' header."
);
}
if (webhookTimestamp.length === 0) {
throw new ComposioWebhookSignatureVerificationError(
"No webhook timestamp was provided. Please pass the value of the 'webhook-timestamp' header."
);
}
// Parse signature - may have multiple signatures prefixed with version (e.g., "v1,base64sig")
const signatures = signature.split(' ');
const v1Signatures: string[] = [];
for (const sig of signatures) {
const [version, value] = sig.split(',');
if (version === 'v1' && value) {
v1Signatures.push(value);
}
}
if (v1Signatures.length === 0) {
throw new ComposioWebhookSignatureVerificationError(
'No valid v1 signature found in the webhook-signature header. ' +
"Expected format: 'v1,base64EncodedSignature'"
);
}
// Compute expected signature: HMAC-SHA256(msgId.timestamp.payload, secret) -> base64
const toSign = `${webhookId}.${webhookTimestamp}.${payload}`;
const expectedSignature = await hmacSha256Base64(secret, toSign);
// Check if any of the provided signatures match
let isValid = false;
for (const providedSignature of v1Signatures) {
if (timingSafeEqual(providedSignature, expectedSignature)) {
isValid = true;
break;
}
}
if (!isValid) {
throw new ComposioWebhookSignatureVerificationError(
'The signature provided is invalid. Please ensure you are using the correct webhook secret.'
);
}
}
/**
* Validates that the webhook timestamp is within the allowed tolerance
* @private
*/
private validateWebhookTimestamp(webhookTimestamp: string, tolerance: number): void {
const timestampSeconds = parseInt(webhookTimestamp, 10);
if (Number.isNaN(timestampSeconds)) {
throw new ComposioWebhookPayloadError(
`Invalid webhook timestamp: ${webhookTimestamp}. Expected Unix timestamp in seconds.`
);
}
const webhookTimeMs = timestampSeconds * 1000;
const currentTime = Date.now();
const timeDifference = Math.abs(currentTime - webhookTimeMs);
if (timeDifference > tolerance * 1000) {
throw new ComposioWebhookSignatureVerificationError(
`The webhook timestamp is outside the allowed tolerance. ` +
`The webhook was sent ${Math.round(timeDifference / 1000)} seconds ago, ` +
`but the maximum allowed age is ${tolerance} seconds.`
);
}
}
}