@devries-cameron20 / composio Mirror · read-only
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, 07:15 UTC

next
mdx 64 lines 4.41 KB
Raw
1 ---
2 title: 'Realtime triggers for Gmail and Google Calendar'
3 description: 'Gmail and Google Calendar triggers now fire the moment something changes, instead of on the next poll.'
4 date: '2026-11-12'
5 ---
6
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
11 ```bash
12 curl -X POST https://backend.composio.dev/api/v3.1/trigger_instances/GMAIL_NEW_GMAIL_MESSAGE/upsert \
13 -H "x-api-key: YOUR_API_KEY" \
14 -H "Content-Type: application/json" \
15 -d '{"user_id": "user-id-123435"}'
16 ```
17
18 ```json
19 {
20 "trigger_id": "ti_xxx",
21 "type": "webhook",
22 "fallback_reason": null,
23 "polling_interval": null
24 }
25 ```
26
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 - **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.
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
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
43 ### Existing triggers
44
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.
46
47 ### Gmail and Calendar on your own OAuth app
48
49 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: `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.
57 </Callout>
58
59 For a smooth, test-first rollout:
60
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, create the Pub/Sub push subscription that delivers to its `webhook_url`, then fill every field on the endpoint.
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.