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.
import requests
url = "https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert"
payload = {
"connectedAuthId": "<string>",
"triggerConfig": {},
"connected_account_id": "<string>",
"user_id": "<string>",
"egress_url": "<string>",
"trigger_config": {},
"polling_interval": 5040,
"version": "latest",
"toolkit_versions": "latest"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connectedAuthId: '<string>',
triggerConfig: {},
connected_account_id: '<string>',
user_id: '<string>',
egress_url: '<string>',
trigger_config: {},
polling_interval: 5040,
version: 'latest',
toolkit_versions: 'latest'
})
};
fetch('https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"connectedAuthId": "<string>",
"triggerConfig": {},
"connected_account_id": "<string>",
"user_id": "<string>",
"egress_url": "<string>",
"trigger_config": {},
"polling_interval": 5040,
"version": "latest",
"toolkit_versions": "latest"
}
'package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert"
payload := strings.NewReader("{\n \"connectedAuthId\": \"<string>\",\n \"triggerConfig\": {},\n \"connected_account_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"egress_url\": \"<string>\",\n \"trigger_config\": {},\n \"polling_interval\": 5040,\n \"version\": \"latest\",\n \"toolkit_versions\": \"latest\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"connectedAuthId\": \"<string>\",\n \"triggerConfig\": {},\n \"connected_account_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"egress_url\": \"<string>\",\n \"trigger_config\": {},\n \"polling_interval\": 5040,\n \"version\": \"latest\",\n \"toolkit_versions\": \"latest\"\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-api-key", "<api-key>");
request.AddJsonBody("{\n \"connectedAuthId\": \"<string>\",\n \"triggerConfig\": {},\n \"connected_account_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"egress_url\": \"<string>\",\n \"trigger_config\": {},\n \"polling_interval\": 5040,\n \"version\": \"latest\",\n \"toolkit_versions\": \"latest\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
false{
"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
}{
"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
}{}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}Authorizations
Path Parameters
Body
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.
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.
2048Response
Successfully upserted trigger instance
import requests
url = "https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert"
payload = {
"connectedAuthId": "<string>",
"triggerConfig": {},
"connected_account_id": "<string>",
"user_id": "<string>",
"egress_url": "<string>",
"trigger_config": {},
"polling_interval": 5040,
"version": "latest",
"toolkit_versions": "latest"
}
headers = {
"x-api-key": "<api-key>",
"Content-Type": "application/json"
}
response = requests.post(url, json=payload, headers=headers)
print(response.text)const options = {
method: 'POST',
headers: {'x-api-key': '<api-key>', 'Content-Type': 'application/json'},
body: JSON.stringify({
connectedAuthId: '<string>',
triggerConfig: {},
connected_account_id: '<string>',
user_id: '<string>',
egress_url: '<string>',
trigger_config: {},
polling_interval: 5040,
version: 'latest',
toolkit_versions: 'latest'
})
};
fetch('https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert', options)
.then(res => res.json())
.then(res => console.log(res))
.catch(err => console.error(err));curl --request POST \
--url https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert \
--header 'Content-Type: application/json' \
--header 'x-api-key: <api-key>' \
--data '
{
"connectedAuthId": "<string>",
"triggerConfig": {},
"connected_account_id": "<string>",
"user_id": "<string>",
"egress_url": "<string>",
"trigger_config": {},
"polling_interval": 5040,
"version": "latest",
"toolkit_versions": "latest"
}
'package main
import (
"fmt"
"strings"
"net/http"
"io"
)
func main() {
url := "https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert"
payload := strings.NewReader("{\n \"connectedAuthId\": \"<string>\",\n \"triggerConfig\": {},\n \"connected_account_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"egress_url\": \"<string>\",\n \"trigger_config\": {},\n \"polling_interval\": 5040,\n \"version\": \"latest\",\n \"toolkit_versions\": \"latest\"\n}")
req, _ := http.NewRequest("POST", url, payload)
req.Header.Add("x-api-key", "<api-key>")
req.Header.Add("Content-Type", "application/json")
res, _ := http.DefaultClient.Do(req)
defer res.Body.Close()
body, _ := io.ReadAll(res.Body)
fmt.Println(string(body))
}HttpResponse<String> response = Unirest.post("https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert")
.header("x-api-key", "<api-key>")
.header("Content-Type", "application/json")
.body("{\n \"connectedAuthId\": \"<string>\",\n \"triggerConfig\": {},\n \"connected_account_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"egress_url\": \"<string>\",\n \"trigger_config\": {},\n \"polling_interval\": 5040,\n \"version\": \"latest\",\n \"toolkit_versions\": \"latest\"\n}")
.asString();using RestSharp;
var options = new RestClientOptions("https://backend.composio.dev/api/v3/trigger_instances/{slug}/upsert");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("x-api-key", "<api-key>");
request.AddJsonBody("{\n \"connectedAuthId\": \"<string>\",\n \"triggerConfig\": {},\n \"connected_account_id\": \"<string>\",\n \"user_id\": \"<string>\",\n \"egress_url\": \"<string>\",\n \"trigger_config\": {},\n \"polling_interval\": 5040,\n \"version\": \"latest\",\n \"toolkit_versions\": \"latest\"\n}", false);
var response = await client.PostAsync(request);
Console.WriteLine("{0}", response.Content);
false{
"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
}{
"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
}{}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}{
"error": {
"message": "<string>",
"code": 123,
"slug": "<string>",
"status": 123,
"request_id": "<string>",
"suggested_fix": "<string>",
"errors": [
"<string>"
]
}
}