Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
docs: correct polling interval wording and scope the realtime claim to new triggers
The 2-minute value is the default polling interval, not a minimum. Drop the minimum-check sentence, say new triggers in the changelog opener, link the Gmail setup only to the trigger description, and tell Gmail custom apps to save the endpoint fields last. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Anshu Garg committed
Nov 11, 2026 at 23:29 UTC
efcbd5a2f67079c28791288c9afa119f38a4d040
5 files changed
+7
-7
docs/content/changelog/11-05-26-gmail-google-calendar-realtime-triggers.mdx
+3
-3
@@ -4,7 +4,7 @@ description: 'Gmail and Google Calendar triggers now fire the moment something c
4
date: '2026-11-05'
5
---
6
7
-Your Gmail and Google Calendar triggers no longer wait for the next poll. Google now tells Composio about a new email or a moved meeting as it happens, and the event reaches your webhook URL in seconds, in the same payload shape your handler already reads.
7
+New Gmail and Google Calendar triggers no longer wait for the next poll. Google now tells Composio about a new email or a moved meeting as it happens, and the event reaches your webhook URL in seconds, in the same payload shape your handler already reads.
8
9
On Composio-managed auth, there's nothing to set up, and you can start right away. Create a trigger the way you always have:
10
@@ -31,7 +31,7 @@ What just happened? The trigger supports both webhooks and polling, so Composio
31
- **Realtime Gmail triggers.** `GMAIL_NEW_GMAIL_MESSAGE` and `GMAIL_EMAIL_SENT_TRIGGER`.
32
- **Realtime Google Calendar triggers.** `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_CREATED_TRIGGER`, `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_UPDATED_TRIGGER`, `GOOGLECALENDAR_GOOGLE_CALENDAR_EVENT_SYNC_TRIGGER`, `GOOGLECALENDAR_EVENT_CANCELED_DELETED_TRIGGER`, and `GOOGLECALENDAR_ATTENDEE_RESPONSE_CHANGED_TRIGGER`. `GOOGLECALENDAR_EVENT_STARTING_SOON_TRIGGER` keeps polling, because it fires on a schedule relative to each event's start time.
33
- **Choose webhook or polling.** Pass `type` as `"webhook"` or `"poll"`. Omit it and Composio uses a webhook whenever it can set one up.
34
-- **`polling_interval`.** Set the minutes between polls with this top-level parameter (`pollingInterval` in TypeScript). It applies when you pass `type: "poll"`, and when a trigger falls back to polling. When you omit `type` or pass `type: "poll"`, Composio checks it before it sets up the trigger, so a value below the toolkit's minimum fails the request.
34
+- **`polling_interval`.** Set the minutes between polls with this top-level parameter (`pollingInterval` in TypeScript). It applies when you pass `type: "poll"`, and when a trigger falls back to polling.
35
- **`fallback_reason`.** When a trigger polls because Composio couldn't set up its webhook, `fallback_reason` says what's missing.
36
37
Python `composio` 0.31.0 and TypeScript `@composio/core` 0.28.0 support `type` and the polling interval. See the [SDK release notes](/docs/changelog/2026/11/03).
@@ -50,7 +50,7 @@ Google Calendar works on your own Google OAuth app with no extra setup.
50
51
Gmail delivers mailbox changes through Google Cloud Pub/Sub, so your app needs a topic and a push subscription in the Google Cloud project that owns your OAuth client. Each Gmail trigger's description walks you through it. Read it with `composio.triggers.get_type("GMAIL_NEW_GMAIL_MESSAGE")` in Python, `composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE')` in TypeScript, or `GET /api/v3.1/triggers_types/GMAIL_NEW_GMAIL_MESSAGE`.
52
53
-Setup is complete once your Gmail webhook endpoint exists and holds every field the [Gmail FAQ](/toolkits/gmail) lists: `topic_name`, `push_service_account_email`, and `push_audience`. Until then, new Gmail triggers keep polling, and `fallback_reason` tells you which piece is missing. Nothing breaks while you set up.
53
+Setup is complete once your Gmail webhook endpoint exists and holds every field: `topic_name`, `push_service_account_email`, and `push_audience`. Until then, new Gmail triggers keep polling, and `fallback_reason` tells you which piece is missing. Nothing breaks while you set up.
54
55
<Callout type="warn">
56
**A note on timing.** Composio can't look inside your Google Cloud project, so it treats your endpoint as ready as soon as you've filled in every field. From then on, new Gmail triggers you create without `type` use the webhook. If your Pub/Sub push subscription isn't delivering to the endpoint's `webhook_url` yet, Gmail's changes won't reach Composio, and those triggers will stay quiet with no error to tell you why. The rollout below keeps you on polling until you've seen an event arrive.
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+1
-1
@@ -181,7 +181,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_G
181
182
Omit `type` to let Composio choose. The response reports what the instance uses. Composio sets `fallback_reason` when the instance polls because it couldn't set up a webhook, for example when your own OAuth app has no [webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) yet.
183
184
-When you omit `type` or pass `type: "poll"`, Composio checks `polling_interval` before it sets up the trigger, so a value below the toolkit's minimum fails the request.
184
+Leave `polling_interval` out to use the toolkit's default.
185
186
## Next
187
docs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdx
+1
-1
@@ -41,7 +41,7 @@ The walkthrough below uses Slack as the example and the [Webhook Endpoints API](
41
42
For Slack, collect the **Signing Secret** from your app's Basic Information page and an **App-Level Token** (`xapp-...`) with the `authorizations:read` scope. Keep both secret. The endpoint verification step below uses `webhook_signing_secret` and `app_token`; it does not require a separate Composio schema-discovery request.
43
44
-Other toolkits take different fields. Gmail, for example, takes `topic_name`, `push_service_account_email`, and `push_audience`.
44
+Other toolkits take different fields. Gmail, for example, takes `topic_name`, `push_service_account_email`, and `push_audience`. Save them last, once its Pub/Sub push subscription is delivering: new Gmail triggers switch to the webhook as soon as all three are set.
45
46
Use the [Webhook Endpoints API](/reference/api-reference/webhook-endpoints) for the supported create, retrieve, replace, and update operations. The committed API contract does not declare `/webhook_endpoints/schema`.
47
docs/content/docs/setting-up-triggers/troubleshooting.mdx
+1
-1
@@ -39,7 +39,7 @@ With Composio-managed OAuth, Composio manages provider ingress. If matching even
39
40
## Test Gmail polling with a new message
41
42
-A new message can take up to one full polling interval to appear. That's the trigger's `polling_interval`. On Composio-managed auth, the shortest allowed interval is 2 minutes. A trigger with a longer interval waits that long. 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
+A new message can take up to one full polling interval to appear. That's the trigger's `polling_interval`, 2 minutes by default. A trigger with a longer interval waits that long. 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.
43
44
Wait for the first successful poll to establish the baseline, then send one new message to the connected mailbox. Keep its Gmail message ID and UTC arrival time, then check the intended trigger instance and your webhook delivery logs after another full polling interval. If you need older messages, fetch them separately with Gmail tools.
45
docs/content/docs/triggers.mdx
+1
-1
@@ -19,7 +19,7 @@ Under the hood, Composio learns about events in one of two ways. It only affects
19
| Kind | How Composio learns about the event | Latency | Examples |
20
|---|---|---|---|
21
| **Realtime** | The provider pushes the event to Composio the moment it happens. | Near-instant | Slack, Asana, Notion, Outlook, Gmail, Google Calendar |
22
-| **Polling** | Composio checks the provider on a schedule. | Up to the trigger's polling interval. On Composio-managed auth, the shortest allowed interval is 2 min | Google Drive, Google Sheets, OneDrive |
22
+| **Polling** | Composio checks the provider on a schedule. | Up to the trigger's polling interval, 2 min by default | Google Drive, Google Sheets, OneDrive |
23
24
Most trigger types use one kind. Some, including the Gmail and Google Calendar triggers, support both: Composio uses realtime delivery whenever it can, and you can choose with `type`. See [Choosing webhook or polling](/docs/setting-up-triggers/creating-triggers#choosing-webhook-or-polling).
25