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: describe triggers that support both webhook and polling on the custom OAuth page
requires_webhook_endpoint_setup covers the webhook only. Until the endpoint is set up, such triggers poll and report fallback_reason. Add Gmail's fields, verification, and where its URL goes beside Slack's. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Anshu Garg committed
Nov 5, 2026 at 15:30 UTC
d3cb194af566b624d30114bb3214ff8c1cfca623
1 file changed
+8
-3
docs/content/docs/setting-up-triggers/custom-oauth-webhooks.mdx
+8
-3
@@ -1,13 +1,15 @@
1
---
2
title: Custom OAuth webhooks
3
description: Register Composio's ingress URL when you bring your own OAuth app
4
-keywords: [webhook endpoint, ingress, byo oauth, custom oauth, requires_webhook_endpoint_setup]
4
+keywords: [webhook endpoint, ingress, byo oauth, custom oauth, requires_webhook_endpoint_setup, fallback_reason, gmail pub/sub]
5
---
6
7
This page is only for **realtime triggers where you bring your own OAuth app**. With Composio-managed OAuth, ingress is already set up and you can skip this entirely. Create the trigger and events flow.
8
9
Some providers only deliver events to URLs you've registered on your OAuth app. When you bring your own app, you register Composio's ingress URL there once, so events can reach Composio. You need this only when the trigger type's `requires_webhook_endpoint_setup` flag is `true`.
10
11
+Some trigger types, like Gmail's, can receive events by webhook or by polling. For those, the flag describes the webhook only: polling needs no endpoint. Until the endpoint is fully set up, Composio creates these triggers as polling triggers and sets `fallback_reason` to what's missing. Once it's set up, new triggers you create without `type` use the webhook. See [Choosing webhook or polling](/docs/setting-up-triggers/creating-triggers#choosing-webhook-or-polling).
12
+
13
Each OAuth app you bring gets its own ingress URL within a project:
14
15
```
@@ -23,7 +25,7 @@ A single OAuth app can serve at most one Composio project: providers accept only
25
26
Every inbound event is signature-checked at ingress before any trigger fires:
27
26
-- **HMAC-SHA256** for Slack, **Ed25519** or shared-token matching for other providers
28
+- **HMAC-SHA256** for Slack, **Google-signed tokens** for Gmail, and **Ed25519** or shared-token matching for other providers
29
- **Timestamp replay protection**: when the provider signs a request timestamp, requests outside the allowed skew window are rejected
30
- **Unsigned or tampered requests** are rejected with `400` at ingress, so third parties can't spoof events onto your triggers
31
@@ -33,12 +35,14 @@ 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
36
-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) or [Notion](/toolkits/notion).
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.
39
40
## Step 1: Collect the provider credentials
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`.
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
48
## Step 2: Create the endpoint
@@ -157,6 +161,7 @@ Paste the `webhook_url` from step 2 into the provider's app dashboard:
161
162
- **Slack** → Event Subscriptions → Request URL
163
- **Notion** → Webhook Endpoints (in the integration's settings)
164
+- **Gmail** → a Pub/Sub push subscription on your topic, with the `webhook_url` as both its endpoint URL and its audience
165
166
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).
167