Skip to main content
POST
Create or update a trigger

Authorizations

x-api-key
string
header
default:your-project-api-key
required

Your Composio project API key. Create or copy it from the Composio dashboard.

Path Parameters

slug
string
required

The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).

Body

application/json
connectedAuthId
string<connectedAccountId>
deprecated

DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.

triggerConfig
object
deprecated

DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.

connected_account_id
string<connectedAccountId>

Connected account nanoid. Optional when user_id is provided — the first active connection for that user and the trigger's toolkit is auto-resolved.

user_id
string

The user id (entity id) that owns the connection. When connected_account_id is omitted, the first active connection for this user and the trigger's toolkit is auto-resolved (same as tool execution). When connected_account_id is also provided, user_id is checked against that connection: always against a SHARED connection's ACL (user_id is then required), and against a PRIVATE connection's owner when the project has 2FA enabled.

egress_url
string<uri> | null

Overrides the delivery URL for this trigger instance only: its events are sent to this HTTPS URL instead of the project webhook URL. Your project webhook subscription is still required and still controls signing (the webhook secret), the payload version and which events are enabled; only the destination changes for this instance. Omit to leave the current value unchanged; pass null to remove the override and deliver to the project webhook URL again.

Maximum string length: 2048
trigger_config
object

Trigger configuration

type
enum<string>

Whether this instance receives events by webhook or by polling, for a trigger that supports both. Omit it to let Composio choose the best one.

Available options:
poll,
webhook
polling_interval
integer

Minutes between polls, for an instance that polls for its events. It is checked whenever the instance could poll, even when Composio tries a webhook first, so an interval outside the toolkit's allowed range fails the request.

Required range: 1 <= x <= 10080
version
string
deprecated

DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.

Example:

"latest"

toolkit_versions

Toolkit version specification. Supports "latest" string or a record mapping toolkit slugs to specific versions.

Example:

"latest"

Response

Successfully upserted trigger instance

trigger_id
string
required

ID of the updated trigger

type
enum<string>
required

How this trigger instance gets events: webhook (the provider notifies) or poll (a scheduled check).

Available options:
webhook,
poll
Example:

"webhook"

fallback_reason
string | null
required

Set when Composio downgraded to a poll-based mechanism instead of webhooks for this trigger.

Example:

"No webhook endpoint found for toolkit \"gmail\". Create a webhook endpoint before setting up triggers."

polling_interval
integer | null
required

Minutes between scheduled polls for a poll instance.

Example:

15