Skip to main content
Triggers let you subscribe to events from a user’s connected app, such as a new Gmail message, a GitHub commit, or a Slack message, and receive the event data as a structured payload at your webhook endpoint. There are two layers to understand:
  • A trigger type is a template that defines what event to listen for and what configuration it needs. For example, GITHUB_COMMIT_EVENT requires an owner and a repo. Each toolkit exposes its own trigger types.
  • A trigger instance is a trigger type scoped to a specific user and connected account. Creating one produces an instance with its own ti_* ID that you can enable, disable, or delete independently.
Reach for these endpoints when you want to:
  • Discover the trigger types a toolkit offers, or fetch one type by slug to inspect its config and payload schema.
  • Create or update a trigger instance for a connected account with the upsert endpoint.
  • List active trigger instances, or enable, disable, and delete an instance by triggerId.
These endpoints authenticate with your project API key in the x-api-key header.
Creating a trigger instance only registers it. To actually receive events, set a webhook URL for your project once, then route incoming events on metadata.trigger_slug. See Subscribing to events.
For the full concept overview, see Triggers.

List active triggers

Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.

List trigger types

Retrieve a list of available trigger types with optional filtering by toolkit. Results are paginated and can be filtered by toolkit.

Get trigger type by slug

Retrieve detailed information about a specific trigger type using its slug identifier

List trigger type enums

Retrieves a list of all available trigger type enum values that can be used across the API from latest versions of the toolkit only

Create or update a trigger

Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Provide either a connected_account_id to pin a specific user connection, or a user_id to auto-resolve the first active connection for that user and the trigger's toolkit. For a trigger that supports both webhooks and polling, Composio chooses the best way for the instance to receive events unless type sets one. When the instance polls because a webhook could not be set up, fallback_reason says why. An existing instance keeps its type, so an upsert asking for the other type returns 409.

Update a trigger

Updates a trigger instance. Pass status to enable or disable it: disabling pauses event listening without deleting the trigger configuration, and re-enabling restores it. When a webhook trigger is disabled, Composio also attempts to remove the webhook it received events through at the provider, once no other active trigger uses it. This runs in the background after the response, with retries if the provider fails. Re-enabling a webhook trigger sets it up with the provider again. Pass egress_url to override where this instance delivers its events (null removes the override); the project webhook subscription is still required and still controls signing, the payload version and which events are enabled. Send either field or both. On a project with 2FA enabled, user_id is required to set egress_url and, whenever sent, must own the connected account behind the trigger. On a shared connected account, user_id is required to enable the trigger or set egress_url, and is checked against the connection's ACL.

Delete a trigger

Permanently deletes a trigger instance. This stops the trigger from listening for events and removes it from your project. When a webhook trigger is deleted, Composio also attempts to remove the webhook it received events through at the provider, once no other active trigger uses it. This runs in the background after the response, with retries if the provider fails. Use the PATCH endpoint with status "disable" if you want to temporarily pause a trigger instead.