Triggers

Create or update a trigger

Changed on

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.

post/api/v3.1/trigger_instances/{slug}/upsert

Request

  • Base URL
    https://backend.composio.dev
  • URL
    https://backend.composio.dev/api/v3.1/trigger_instances/{slug}/upsert
  • Auth
    • API key in header x-api-key
    • or API key in header x-user-api-key

Path parameters

slugstring required

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

Request body

connectedAuthIdstring connectedAccountId

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

triggerConfigobject

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

connected_account_idstring 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_idstring

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_urlstring uri nullable

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.

trigger_configobject

Trigger configuration

versionstring

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

Example request

{
  "version": "latest"
}

Response

Successfully upserted trigger instance

trigger_idstring required

ID of the updated trigger

Changes

  • 98956f31abf3Revision changes
    • breaking

      the request property / became not nullable

    • breaking

      the request property / became not nullable

    • breaking

      the / request property type changed from no type to object

    • info

      api operation id postV3_1TriggerInstancesBySlugUpsert removed and replaced with postTriggerInstancesBySlugUpsert

    • info

      added the new optional request property

    • info

      added the non-success response with the status

  • 1d3aac1128efRevision changes
    • warning

      removed the optional property from the response with the status

    • warning

      removed the optional property from the response with the status