@devries-cameron20 / composio Mirror · read-only / commits / 7017afdff
Fork 0

Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 21, 08:30 UTC

docs: add trigger delivery and reply-loop troubleshooting

Vinayak Agarwal committed Oct 20, 2026 at 13:09 UTC 7017afdffc5b4423448c8b6134be66c9f16febc2
4 files changed +82 -4
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+1 -1
@@ -111,7 +111,7 @@ const trigger = await composio.triggers.create(userId, 'GITHUB_COMMIT_EVENT', {
111
112 Trigger instances default to the `'latest'` toolkit version. If you parse payloads against a fixed schema, [pin a version](/docs/tools-direct/toolkit-versioning#choosing-between-latest-and-a-pinned-version) at SDK initialization.
113
114 -That's it. The trigger is active. Next, [receive its events](/docs/setting-up-triggers/subscribing-to-events).
114 +The trigger instance is created. Next, [receive its events](/docs/setting-up-triggers/subscribing-to-events) and test with a new matching event in the provider. If nothing arrives, follow [Troubleshooting triggers](/docs/setting-up-triggers/troubleshooting).
115
116 ## Next
117
docs/content/docs/setting-up-triggers/managing-triggers.mdx
+12 -2
@@ -26,7 +26,10 @@ for trigger in active.items:
26
27 # Paginate with cursor
28 if active.next_cursor:
29 - next_page = composio.triggers.list_active(cursor=active.next_cursor)
29 + next_page = composio.triggers.list_active(
30 + connected_account_ids=["ca_def456"],
31 + cursor=active.next_cursor,
32 + )
33 ```
34 </Tab>
35 <Tab value="TypeScript">
@@ -45,7 +48,10 @@ for (const trigger of active.items) {
48
49 // Paginate with cursor
50 if (active.nextCursor) {
48 - const nextPage = await composio.triggers.listActive({ cursor: active.nextCursor });
51 + const nextPage = await composio.triggers.listActive({
52 + connectedAccountIds: ['ca_def456'],
53 + cursor: active.nextCursor,
54 + });
55 }
56 ```
57 </Tab>
@@ -59,6 +65,8 @@ if (active.nextCursor) {
65 | `auth_config_ids` / `authConfigIds` | Array of auth config IDs |
66 | `show_disabled` / `showDisabled` | Include disabled triggers (default: `false`) |
67
68 +Keep the same filters on every page. To find paused instances after reconnecting an account, include `show_disabled=True` in Python or `showDisabled: true` in TypeScript.
69 +
70 ## Enable / Disable triggers
71
72 Pause a trigger temporarily without deleting it:
@@ -110,3 +118,5 @@ await composio.triggers.delete('ti_abcd123');
118 <Callout type="warn">
119 Deleting a trigger is permanent. Use `disable()` instead to temporarily stop receiving events.
120 </Callout>
121 +
122 +If an enabled trigger isn't delivering events, follow [Troubleshooting triggers](/docs/setting-up-triggers/troubleshooting).
docs/content/docs/setting-up-triggers/meta.json
+2 -1
@@ -4,6 +4,7 @@
4 "creating-triggers",
5 "subscribing-to-events",
6 "managing-triggers",
7 - "custom-oauth-webhooks"
7 + "custom-oauth-webhooks",
8 + "troubleshooting"
9 ]
10 }
docs/content/docs/setting-up-triggers/troubleshooting.mdx new
+67
@@ -0,0 +1,67 @@
1 +---
2 +title: Troubleshooting triggers
3 +description: Find where events stop between your provider, Composio, and your webhook handler
4 +keywords: [triggers, troubleshooting, missing events, Gmail, polling, webhook delivery]
5 +---
6 +
7 +An active trigger instance confirms that the trigger exists. Test delivery separately: the provider must produce a matching event, Composio must receive or poll it, and your webhook handler must accept it.
8 +
9 +## Check the connection and identifiers
10 +
11 +Record the trigger instance ID and its connected account before changing the configuration. Keep these identifiers separate:
12 +
13 +| Value | Purpose |
14 +| --- | --- |
15 +| `GMAIL_NEW_GMAIL_MESSAGE` | A trigger type slug. It selects which event to watch. |
16 +| `ti_...` | A trigger instance ID. Use it to inspect, enable, disable, or delete that instance. |
17 +| `ca_...` | A connected account ID. It selects the provider account to watch. |
18 +| `user_id` / `userId` | Your application's user ID, supplied when that account was connected. |
19 +| `composio.trigger.message` | The outbound webhook event type for trigger events. |
20 +
21 +An organization member ID or trigger instance ID cannot replace a connected account ID. If you have multiple connections for the same toolkit, [target the specific connected account](/docs/setting-up-triggers/creating-triggers#targeting-a-specific-connected-account) and inspect that same trigger instance's logs.
22 +
23 +Check that both the connected account and the trigger are enabled. Successfully executing a tool verifies a different path from receiving a trigger event.
24 +
25 +## Separate provider ingress from outbound delivery
26 +
27 +Use the trigger logs to locate the first missing step:
28 +
29 +| What you see | What to check next |
30 +| --- | --- |
31 +| No trigger event appears | Confirm the provider event matches the trigger type and configuration. For polling triggers, allow the polling interval to pass. For realtime triggers, check provider ingress. |
32 +| A trigger event exists, but your app receives nothing | Inspect the project's outbound webhook subscription, destination URL, enabled events, and delivery response. |
33 +| Your app receives a request, but the handler rejects it | Check the signing secret, raw request body, timestamp, and handler logs using [signature verification](/docs/setting-up-triggers/subscribing-to-events#verifying-signatures). |
34 +
35 +Your outbound subscription must include `composio.trigger.message`. A toolkit's trigger slug is not a webhook subscription event type. See [project subscriptions](/docs/setting-up-triggers/subscribing-to-events#manage-project-subscriptions).
36 +
37 +With Composio-managed OAuth, Composio manages provider ingress. If matching events never reach the trigger logs, contact support with the evidence below. If you bring your own OAuth app, check whether the trigger requires [custom OAuth webhook setup](/docs/setting-up-triggers/custom-oauth-webhooks), including provider verification and signing credentials.
38 +
39 +## Test Gmail polling with a new message
40 +
41 +Gmail polling on Composio-managed auth can take up to about 15 minutes. An empty legacy `last_synced_at` field alone does not establish that polling has stopped. Gmail polling uses a mailbox history cursor, and its first successful poll establishes a baseline. Messages that existed before that baseline are not a backfill.
42 +
43 +Send one new message to the connected mailbox after setup. Keep its Gmail message ID and UTC arrival time, then check the intended trigger instance and your webhook delivery logs after a full polling interval. If you need older messages, fetch them separately with Gmail tools.
44 +
45 +### Prevent reply loops
46 +
47 +<Callout type="warn">
48 +Before an agent replies to a `GMAIL_NEW_GMAIL_MESSAGE` event, compare the event's `sender` with the connected mailbox address and its send-as aliases. Skip replies to messages sent by those addresses. This prevents a reply loop if a sent reply appears in the new-message events. Creating `GMAIL_EMAIL_SENT_TRIGGER` does not suppress events from the new-message trigger.
49 +</Callout>
50 +
51 +## Resume triggers after reconnecting
52 +
53 +Disabling a connected account also disables its triggers. Re-enabling the account does not automatically re-enable those triggers. [List the disabled instances](/docs/setting-up-triggers/managing-triggers#listing-active-triggers), then enable the ones you want to resume.
54 +
55 +If you connect under a different application user ID, you create a new connected account. Existing trigger instances remain attached to the original connection. Create triggers against the new connection when you intend to watch it.
56 +
57 +## Send a reproducible support report
58 +
59 +Include the following so support can correlate provider activity, trigger events, and webhook deliveries:
60 +
61 +- Your project ID, trigger type, trigger instance ID, and connected account ID.
62 +- Whether you use Composio-managed OAuth or your own OAuth app.
63 +- The relevant trigger configuration, with secrets removed.
64 +- One provider event's ID and UTC timestamp, such as a Gmail message ID or Notion page ID and edit time.
65 +- Whether the event appears in Composio's trigger logs, and any webhook delivery status or request/log ID.
66 +
67 +Share identifiers and redacted errors. Keep API keys, OAuth tokens, and webhook signing secrets out of the report.