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, 06:00 UTC
docs: add a Gmail webhook FAQ and keep deprecated fields out of the guides
Add the Gmail Pub/Sub setup to the Gmail toolkit FAQ, link it from the custom OAuth webhooks page, and drop the interval deprecation and the 409 note from the guides. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Anshu Garg committed
Nov 5, 2026 at 16:27 UTC
7f4fb9ab3205e4465e5f9160492d2fc7637675c6
4 files changed
+26
-7
docs/content/changelog/11-05-26-gmail-google-calendar-instant-triggers.mdx
+2
-2
@@ -6,7 +6,7 @@ date: '2026-11-05'
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.
8
9
-On Composio-managed auth, there's nothing to set up. Create a trigger the way you always have:
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 \
@@ -42,7 +42,7 @@ Python `composio` 0.31.0 and TypeScript `@composio/core` 0.28.0 support `type` a
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. An existing trigger keeps the type it was created with, so an upsert that asks for the other type returns `409`.
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
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+1
-3
@@ -181,9 +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
-`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.
184
+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
## Next
187
docs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdx
+1
-1
@@ -35,7 +35,7 @@ Every inbound event is signature-checked at ingress before any trigger fires:
35
36
You can also manage ingress endpoints through `composio.webhooks.endpoints` in either SDK. Use `list()` and `get()` to inspect endpoints, `create()` to register one, and `replace()` or `update()` to change its configuration.
37
38
-The walkthrough below uses Slack as the example and the [Webhook Endpoints API](/reference/api-reference/webhook-endpoints). The steps are the same for every toolkit; only the credentials and where you paste the URL differ. For setup notes specific to each toolkit, see its FAQ section, for example [Slack](/toolkits/slack) or [Notion](/toolkits/notion). Gmail's trigger descriptions list the Pub/Sub topic and push subscription it needs.
38
+The walkthrough below uses Slack as the example and the [Webhook Endpoints API](/reference/api-reference/webhook-endpoints). For setup notes specific to each toolkit, see its FAQ section, for example [Slack](/toolkits/slack), [Notion](/toolkits/notion), or [Gmail](/toolkits/gmail).
39
40
## Step 1: Collect the provider credentials
41
docs/content/toolkits/faq/gmail.md
+22
-1
@@ -26,7 +26,28 @@ The user's access token is no longer valid. Common causes: the user revoked acce
26
27
## Why is my Gmail trigger slow?
28
29
-Gmail triggers poll roughly every minute by default. If you need lower latency, consider using webhooks or Google Pub/Sub integrations.
29
+Your trigger is probably polling. Gmail triggers use webhooks on Composio-managed auth, so events arrive in seconds, but a trigger polls when:
30
+
31
+- It was created as a polling trigger. Composio doesn't move existing triggers to webhooks; delete the trigger and create it again.
32
+- You passed `type: "poll"` when you created it.
33
+- Your own OAuth app has no complete Gmail webhook endpoint yet. See the next question.
34
+
35
+A polling trigger waits up to its `polling_interval` between checks. [List the trigger](/docs/setting-up-triggers/managing-triggers#listing-active-triggers) and read its `type` and `fallback_reason` to see which case applies.
36
+
37
+## How do I set up Gmail webhooks with my own OAuth app?
38
+
39
+Gmail delivers mailbox changes through Google Cloud Pub/Sub. Set it up once per OAuth app, in the Google Cloud project that owns your OAuth client:
40
+
41
+1. Enable the Gmail API and the Cloud Pub/Sub API.
42
+2. Create a Pub/Sub topic. Its full name is `projects/<project-id>/topics/<topic-id>`. On the topic, grant `gmail-api-push@system.gserviceaccount.com` the Pub/Sub Publisher role (`roles/pubsub.publisher`).
43
+3. Create a service account only for push deliveries, for example `composio-gmail-push`. Give it no roles and create no keys: Pub/Sub uses it only to sign each push.
44
+4. [Create a Gmail webhook endpoint](/docs/setting-up-triggers/custom-oauth-webhooks) with your OAuth client ID, and note its `webhook_url`.
45
+5. Create a push subscription on the topic. Set its endpoint URL to the `webhook_url`, turn on authentication with the service account, and set the audience to the same `webhook_url`. Leave payload unwrapping off, and set the subscription to never expire.
46
+6. On the endpoint, set `topic_name` to the topic's full name, `push_service_account_email` to the service account's email, and `push_audience` to the `webhook_url`.
47
+
48
+Until the endpoint has all three fields, new Gmail triggers poll, and their `fallback_reason` says what's missing. Once it does, new triggers you create without `type` use the webhook straight away. That's why the fields come last, after the push subscription is delivering.
49
+
50
+If pushes don't arrive, check that Pub/Sub's service agent, `service-<project-number>@gcp-sa-pubsub.iam.gserviceaccount.com`, can sign tokens for the service account. If it can't, grant it the Service Account Token Creator role on that account. Google documents its side in [Gmail push notifications](https://developers.google.com/workspace/gmail/api/guides/push).
51
52
## Why am I getting "Quota Exhausted" or "rate limit exhausted"?
53