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: announce instant Gmail and Google Calendar triggers
Add the changelog entry and document choosing webhook or polling with type and polling_interval, the Gmail Pub/Sub setup order for custom OAuth apps, and how to read fallback_reason. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Anshu Garg committed
Nov 5, 2026 at 14:22 UTC
5345122555f176fc7f179e8e4531504c742c02a0
5 files changed
+135
-4
docs/content/changelog/11-05-26-gmail-google-calendar-instant-triggers.mdx
new
+63
@@ -0,0 +1,63 @@
1
+---
2
+title: 'Instant triggers for Gmail and Google Calendar'
3
+description: 'Gmail and Google Calendar triggers can now receive events by webhook, so a change reaches you in seconds instead of on the next poll.'
4
+date: '2026-11-05'
5
+---
6
+
7
+A new email or a moved meeting no longer has to wait for the next poll. Google now tells Composio the moment something changes, and the event reaches your webhook URL in the same payload shape you already handle.
8
+
9
+- **Composio-managed auth:** new triggers use webhooks automatically. There's nothing to set up.
10
+- **Existing triggers:** they keep polling, exactly as before. To move one to webhooks, delete it and create it again.
11
+- **Your own Google OAuth app:** Calendar needs no setup. Gmail needs a Pub/Sub topic in your Google Cloud project, and its triggers keep polling until that's in place.
12
+
13
+### Supported triggers
14
+
15
+- **Gmail:** `GMAIL_NEW_GMAIL_MESSAGE` and `GMAIL_EMAIL_SENT_TRIGGER`.
16
+- **Google Calendar:** `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`.
17
+
18
+`GOOGLECALENDAR_EVENT_STARTING_SOON_TRIGGER` keeps polling, because it fires on a schedule relative to each event's start time.
19
+
20
+### Choose webhook or polling
21
+
22
+When a trigger supports both, Composio uses a webhook whenever one can be set up. Pass `type` as `"webhook"` or `"poll"` to choose yourself. The response tells you what the instance ended up with. Here, a custom Gmail app has no webhook endpoint yet, so the instance polls:
23
+
24
+```bash
25
+curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
26
+ -H "x-api-key: YOUR_API_KEY" \
27
+ -H "Content-Type: application/json" \
28
+ -d '{"user_id": "user-id-123435"}'
29
+```
30
+
31
+```json
32
+{
33
+ "trigger_id": "ti_xxx",
34
+ "type": "poll",
35
+ "fallback_reason": "No webhook endpoint found for toolkit \"gmail\". Create a webhook endpoint before setting up triggers.",
36
+ "polling_interval": 15
37
+}
38
+```
39
+
40
+`fallback_reason` is set only when an instance polls because its webhook couldn't be set up, and it names what's missing. An existing instance keeps the type it was created with, so an upsert that asks for the other type returns `409`.
41
+
42
+Python `composio` 0.31.0 and TypeScript `@composio/core` 0.28.0 accept `type` and the polling interval. See the [SDK release notes](/docs/changelog/2026/11/03).
43
+
44
+### `polling_interval` replaces `interval`
45
+
46
+Set the minutes between polls with the new top-level `polling_interval` parameter (`pollingInterval` in TypeScript). It applies whenever an instance polls: when you pass `type: "poll"`, and when a webhook isn't available and the instance falls back. Composio checks it even when the instance ends up on a webhook, so a value outside the toolkit's allowed range fails the request.
47
+
48
+`interval` inside `trigger_config` is deprecated. It still works when you don't pass `polling_interval`.
49
+
50
+### Gmail on your own OAuth app
51
+
52
+Gmail delivers mailbox changes through Google Cloud Pub/Sub, so a custom Gmail app needs a topic and a push subscription in the Google Cloud project that owns your OAuth client. Each Gmail trigger's description lists the steps. 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`.
53
+
54
+Setup is complete once your Gmail [webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) exists and holds every required field: `topic_name`, `push_service_account_email`, and `push_audience`. Until then, new Gmail triggers poll, and their `fallback_reason` says what's missing.
55
+
56
+From the moment setup is complete, every new Gmail trigger created without `type` uses a webhook. If the Pub/Sub push subscription isn't delivering to the endpoint's `webhook_url` yet, those triggers stay silent: no events and no error.
57
+
58
+To switch over without missing an email:
59
+
60
+1. Pass `type: "poll"` when you create Gmail triggers, so new triggers keep polling while you set up.
61
+2. Create the webhook endpoint, fill every field, and create the Pub/Sub push subscription that delivers to its `webhook_url`.
62
+3. Create a few test triggers with `type: "webhook"`, send yourself an email, and confirm the events arrive.
63
+4. Pass `type: "webhook"`, or drop `type`, for new triggers. Recreate your existing polling triggers to move them over.
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+49
@@ -136,6 +136,55 @@ Trigger instances default to the `'latest'` toolkit version. If you parse payloa
136
137
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).
138
139
+## Choosing webhook or polling
140
+
141
+Some trigger types, including the Gmail and Google Calendar triggers, can receive events by webhook or by polling. Composio uses a webhook whenever one can be set up. Pass `type` as `"webhook"` or `"poll"` to choose yourself, and `polling_interval` to set the minutes between polls.
142
+
143
+<Tabs groupId="language" items={['Python', 'TypeScript', 'API']} persist>
144
+ <Tab value="Python">
145
+```python
146
+from composio import Composio
147
+
148
+composio = Composio()
149
+
150
+trigger = composio.triggers.create(
151
+ slug="GMAIL_NEW_GMAIL_MESSAGE",
152
+ user_id="user-id-123435",
153
+ type="poll",
154
+ polling_interval=15,
155
+)
156
+print(trigger.type, trigger.polling_interval, trigger.fallback_reason)
157
+```
158
+ </Tab>
159
+ <Tab value="TypeScript">
160
+```typescript
161
+import { Composio } from '@composio/core';
162
+
163
+const composio = new Composio();
164
+
165
+const trigger = await composio.triggers.create('user-id-123435', 'GMAIL_NEW_GMAIL_MESSAGE', {
166
+ type: 'poll',
167
+ pollingInterval: 15,
168
+});
169
+console.log(trigger.type, trigger.pollingInterval, trigger.fallbackReason);
170
+```
171
+ </Tab>
172
+ <Tab value="API">
173
+```bash
174
+curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
175
+ -H "x-api-key: $COMPOSIO_API_KEY" \
176
+ -H "Content-Type: application/json" \
177
+ -d '{"user_id": "user-id-123435", "type": "poll", "polling_interval": 15}'
178
+```
179
+ </Tab>
180
+</Tabs>
181
+
182
+Omit `type` to let Composio choose. The response reports what the instance uses. `fallback_reason` is set when the instance polls because its webhook couldn't be set up, for example when your own OAuth app has no [webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) yet.
183
+
184
+`polling_interval` replaces the `interval` field in `trigger_config`, which still works but is deprecated. Composio checks `polling_interval` whenever the instance could poll, so a value outside the toolkit's allowed range fails the request even when the instance ends up on a webhook.
185
+
186
+An instance keeps the type it was created with. An upsert that asks for the other type returns `409`, so delete the trigger and create it again to switch.
187
+
188
## Next
189
190
<Card icon={<Plug />} title="Receiving events" href="/docs/setting-up-triggers/subscribing-to-events" description="Get trigger events locally with the SDK or in production over your webhook URL" />
docs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdx
+15
@@ -160,6 +160,21 @@ Paste the `webhook_url` from step 2 into the provider's app dashboard:
160
161
For providers that issue a verification challenge on save (Slack `url_verification`, Notion's verification token, and so on), Composio responds automatically, with no handshake code on your side. Once the provider accepts the URL, go [create your trigger](/docs/setting-up-triggers/creating-triggers).
162
163
+## Gmail push notifications
164
+
165
+Gmail delivers mailbox changes through Google Cloud Pub/Sub instead of a request URL on your OAuth app. You create a topic and a push subscription in the Google Cloud project that owns your OAuth client. Each Gmail trigger's description lists the steps; read it with `composio.triggers.get_type("GMAIL_NEW_GMAIL_MESSAGE")` in Python or `composio.triggers.getType('GMAIL_NEW_GMAIL_MESSAGE')` in TypeScript. The Gmail endpoint takes three fields: `topic_name`, `push_service_account_email`, and `push_audience`.
166
+
167
+Until the endpoint exists with all three fields, new Gmail triggers poll, and their `fallback_reason` names what's missing. Once all three are set, every new Gmail trigger created without `type` uses the webhook. If the Pub/Sub push subscription isn't delivering to the endpoint's `webhook_url` by then, those triggers receive nothing and report no error.
168
+
169
+To switch over without missing an email:
170
+
171
+1. Pass `type: "poll"` when you create Gmail triggers, so new triggers keep polling while you set up.
172
+2. Create the endpoint, fill all three fields, and create the Pub/Sub push subscription that delivers to its `webhook_url`.
173
+3. Create a few test triggers with `type: "webhook"`, send yourself an email, and confirm the events arrive.
174
+4. Pass `type: "webhook"`, or drop `type`, for new triggers. An existing trigger keeps polling until you delete it and create it again.
175
+
176
+See [Choosing webhook or polling](/docs/setting-up-triggers/creating-triggers#choosing-webhook-or-polling) for `type` and `polling_interval`.
177
+
178
## Updating an endpoint
179
180
To rotate the signing secret or update any single field, `PATCH` it (other fields are preserved):
docs/content/docs/setting-up-triggers/troubleshooting.mdx
+3
-1
@@ -31,6 +31,8 @@ Use the trigger logs to locate the first missing step:
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
+| A Gmail or Google Calendar trigger polls instead of using a webhook | [List the trigger](/docs/setting-up-triggers/managing-triggers#listing-active-triggers) and read its `type` and `fallback_reason`. `fallback_reason` names what the webhook setup is missing. |
35
+| A Gmail webhook trigger on your own OAuth app receives nothing | Check that the Pub/Sub push subscription delivers to the endpoint's `webhook_url`, with the service account and audience set on the endpoint. See [Gmail push notifications](/docs/setting-up-triggers/custom-oauth-webhooks#gmail-push-notifications). |
36
37
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).
38
@@ -38,7 +40,7 @@ With Composio-managed OAuth, Composio manages provider ingress. If matching even
40
41
## Test Gmail polling with a new message
42
41
-A new message can take up to one full polling interval to appear. That's the `interval` set on the trigger. 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.
43
+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.
44
45
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.
46
docs/content/docs/triggers.mdx
+5
-3
@@ -14,12 +14,14 @@ Composio delivers every event to one destination you control: your webhook URL.
14
15
## Realtime vs polling
16
17
-Under the hood, Composio learns about events in one of two ways. You don't configure this. It's a property of the trigger type, and it only affects how quickly an event reaches you.
17
+Under the hood, Composio learns about events in one of two ways. It only affects how quickly an event reaches you.
18
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 |
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 | Gmail, Google Calendar |
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 |
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 be set up, and you can choose with `type`. See [Choosing webhook or polling](/docs/setting-up-triggers/creating-triggers#choosing-webhook-or-polling).
25
26
Either way, the event lands in the same place: your subscription or webhook URL, in the same payload shape.
27