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(triggers): add Webhook Endpoints API pointer + Notion ingress FAQ
- Single Webhook Endpoints API pointer at Step 2 of creating-triggers, mirroring the Subscriptions API pointer pattern; same pointer added to the Webhook Endpoint glossary entry. - Reword Slack-walkthrough intro to direct readers to per-toolkit FAQ (Slack, Notion). - Add "How do I set up the Notion webhook ingress endpoint?" FAQ covering the reverse-direction verification flow (token from Composio pasted back into Notion). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
Anshu Garg committed
May 11, 2026 at 12:31 UTC
73a5ccf2384f6fb1582dcb982fc7051b83c2013a
3 files changed
+32
-2
docs/content/docs/glossary.mdx
+1
-1
@@ -124,7 +124,7 @@ A specific, active trigger scoped to a user's connected account.
124
</GlossaryTerm>
125
126
<GlossaryTerm name="Webhook Endpoint">
127
-The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures it for you in most cases. When a trigger type's `requires_webhook_endpoint_setup` flag is true, you configure it yourself once per OAuth app. See [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
127
+The ingress URL Composio issues per OAuth app for webhook triggers, plus the signing secret used to verify each inbound request. Composio configures it for you in most cases. When a trigger type's `requires_webhook_endpoint_setup` flag is true, you configure it yourself once per OAuth app via the [Webhook Endpoints API](/reference/api-reference/webhooks). See [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
128
</GlossaryTerm>
129
130
<GlossaryTerm name="Webhook Subscription">
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+3
-1
@@ -41,7 +41,7 @@ Every inbound event is signature-checked at ingress before any trigger fires:
41
**Sharing one OAuth app across projects?** Consolidate to a single project or register separate OAuth apps per project before continuing.
42
</Callout>
43
44
-The steps below use Slack. Other toolkits follow the same flow with different setup fields.
44
+The walkthrough below uses Slack as the example. For setup notes specific to each toolkit, see its FAQ section — e.g., [Slack](/toolkits/slack), [Notion](/toolkits/notion).
45
46
### Step 1: Discover what credentials the endpoint needs
47
@@ -76,6 +76,8 @@ Sample response:
76
77
### Step 2: Create the endpoint
78
79
+Call the [Webhook Endpoints API](/reference/api-reference/webhooks) with the toolkit slug and your OAuth `client_id`:
80
+
81
```bash
82
curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
83
-H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
docs/content/toolkits/faq/notion.md
+28
@@ -14,4 +14,32 @@ No. Notion controls access by granting integrations access to specific pages and
14
15
It depends on the integration type. OAuth apps (public) let users select which pages to share during authorization. Internal integrations (API key) have page access managed in the integration settings.
16
17
+## How do I set up the Notion webhook ingress endpoint?
18
+
19
+With Composio-managed Notion credentials, the webhook ingress endpoint is already provisioned — just create the trigger. If you bring your own Notion OAuth app, the verification flow runs in reverse from Slack's: Notion sends a verification token to the ingress endpoint, and you paste that token back into Notion to finalize.
20
+
21
+1. **Create the endpoint.**
22
+
23
+ ```bash
24
+ curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
25
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
26
+ -H "Content-Type: application/json" \
27
+ -d '{"toolkit_slug": "notion", "client_id": "<YOUR_NOTION_OAUTH_CLIENT_ID>"}'
28
+ ```
29
+
30
+ Save the returned `id` and `webhook_url`.
31
+
32
+2. **Paste the `webhook_url` into Notion** under your integration's Webhook settings. Notion will POST a verification token to the URL.
33
+
34
+3. **Read the token from Composio.**
35
+
36
+ ```bash
37
+ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
38
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
39
+ ```
40
+
41
+ The token is in `data.webhook_signing_secret`.
42
+
43
+4. **Paste the token back into Notion's verify field** to complete setup. Continue with [Creating triggers](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#using-the-sdk).
44
+
45
---