@devries-cameron20 / composio-1 / commits / 5ab22f4bf
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.

docs: rework the instant triggers changelog to the repo's changelog guide

Follow docs-decisions' changelog template (intro, What's new, deprecation callout) and the good-docs-writing voice: a runnable example up top, active voice, and the Gmail silent-trigger gotcha in a warning callout. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Anshu Garg committed Nov 5, 2026 at 15:21 UTC 5ab22f4bf9d2f444694d71aad435c7a5c21a9d68
4 files changed +41 -36
docs/content/changelog/11-05-26-gmail-google-calendar-instant-triggers.mdx
+33 -32
@@ -1,25 +1,12 @@
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.'
3 +description: 'Gmail and Google Calendar triggers now fire the moment something changes, 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.
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.
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:
9 +On Composio-managed auth, there's nothing to set up. Create a trigger the way you always have:
10
11 ```bash
12 curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
@@ -31,33 +18,47 @@ curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_G
18 ```json
19 {
20 "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
21 + "type": "webhook",
22 + "fallback_reason": null,
23 + "polling_interval": null
24 }
25 ```
26
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`.
27 +What just happened? The trigger supports both webhooks and polling, so Composio picked the webhook. The response's `type` tells you which one each trigger uses.
28 +
29 +### What's new
30 +
31 +- **Instant Gmail triggers.** `GMAIL_NEW_GMAIL_MESSAGE` and `GMAIL_EMAIL_SENT_TRIGGER`.
32 +- **Instant 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. Composio checks it even when the trigger ends up on a webhook, so a value outside the toolkit's allowed range fails the request.
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).
38
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).
39 +<Callout>
40 +**Deprecated: `interval` in `trigger_config`.** Use the top-level `polling_interval` instead. `interval` keeps working when you don't pass `polling_interval`.
41 +</Callout>
42
44 -### `polling_interval` replaces `interval`
43 +### Existing triggers
44
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.
45 +Composio doesn't move your existing triggers. They keep polling exactly as before, so nothing changes under you. To move one to webhooks, delete it and create it again. An existing trigger keeps the type it was created with, so an upsert that asks for the other type returns `409`.
46
48 -`interval` inside `trigger_config` is deprecated. It still works when you don't pass `polling_interval`.
47 +### Gmail and Calendar on your own OAuth app
48
50 -### Gmail on your own OAuth app
49 +Google Calendar works on your own Google OAuth app with no extra setup.
50
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`.
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
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.
53 +Setup is complete once your Gmail [webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) 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
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.
55 +<Callout type="warn">
56 +Once the endpoint is complete, every new Gmail trigger you create without `type` uses the webhook right away. If the Pub/Sub push subscription isn't delivering to the endpoint's `webhook_url` yet, those triggers fire nothing, and no error tells you.
57 +</Callout>
58
58 -To switch over without missing an email:
59 +For a smooth, test-first rollout:
60
60 -1. Pass `type: "poll"` when you create Gmail triggers, so new triggers keep polling while you set up.
61 +1. Create Gmail triggers with `type: "poll"` while you set up, so the switch can't catch you halfway.
62 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.
63 +3. Create a few test triggers with `type: "webhook"`, send yourself an email, and watch the event arrive.
64 +4. Switch new triggers to `type: "webhook"`, or drop `type`. Recreate your existing polling triggers to move them over.
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+2 -2
@@ -138,7 +138,7 @@ The trigger instance is created. Next, [receive its events](/docs/setting-up-tri
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.
141 +Some trigger types, including the Gmail and Google Calendar triggers, can receive events by webhook or by polling. Composio uses a webhook whenever it can set one 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">
@@ -179,7 +179,7 @@ curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_G
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.
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 `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
docs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdx
+5 -1
@@ -164,7 +164,11 @@ For providers that issue a verification challenge on save (Slack `url_verificati
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.
167 +Until the endpoint exists with all three fields, new Gmail triggers poll, and their `fallback_reason` names what's missing.
168 +
169 +<Callout type="warn">
170 +**New Gmail triggers switch to the webhook as soon as the endpoint is complete.** Once all three fields are set, every new Gmail trigger you create 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.
171 +</Callout>
172
173 To switch over without missing an email:
174
docs/content/docs/triggers.mdx
+1 -1
@@ -21,7 +21,7 @@ Under the hood, Composio learns about events in one of two ways. It only affects
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).
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
26 Either way, the event lands in the same place: your subscription or webhook URL, in the same payload shape.
27