Create or update a triggerv3.1
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.
Project API key authentication
In: header
Path Parameters
The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).
Request Body
application/json
DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.
connectedAccountIdDEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.
Connected account nanoid. Optional when user_id is provided — the first active connection for that user and the trigger's toolkit is auto-resolved.
connectedAccountIdThe 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.
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.
uriTrigger configuration
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.
pollwebhookMinutes 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.
DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.
Toolkit version specification. Supports "latest" string or a record mapping toolkit slugs to specific versions.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
application/json
import requestsurl = "https://example.com/api/v3.1/trigger_instances/string/upsert"body = """{}"""response = requests.request("POST", url, data = body, headers = { "Content-Type": "application/json"})print(response.text){ "trigger_id": "string", "type": "webhook", "fallback_reason": "No webhook endpoint found for toolkit \"gmail\". Create a webhook endpoint before setting up triggers.", "polling_interval": 15}