Skip to content

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

Anshu Garg73a5ccf2384f
diff --git a/docs/content/docs/glossary.mdx b/docs/content/docs/glossary.mdx
index ae37d7af4..7ce69f5a7 100644
--- a/docs/content/docs/glossary.mdx
+++ b/docs/content/docs/glossary.mdx
@@ -124,7 +124,7 @@ A specific, active trigger scoped to a user's connected account.
</GlossaryTerm>
<GlossaryTerm name="Webhook Endpoint">
-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).
+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).
</GlossaryTerm>
<GlossaryTerm name="Webhook Subscription">
diff --git a/docs/content/docs/setting-up-triggers/creating-triggers.mdx b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
index 0f5f2fc58..5bcaa9580 100644
--- a/docs/content/docs/setting-up-triggers/creating-triggers.mdx
+++ b/docs/content/docs/setting-up-triggers/creating-triggers.mdx
@@ -41,7 +41,7 @@ Every inbound event is signature-checked at ingress before any trigger fires:
**Sharing one OAuth app across projects?** Consolidate to a single project or register separate OAuth apps per project before continuing.
</Callout>
-The steps below use Slack. Other toolkits follow the same flow with different setup fields.
+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).
### Step 1: Discover what credentials the endpoint needs
@@ -76,6 +76,8 @@ Sample response:
### Step 2: Create the endpoint
+Call the [Webhook Endpoints API](/reference/api-reference/webhooks) with the toolkit slug and your OAuth `client_id`:
+
```bash
curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
-H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
diff --git a/docs/content/toolkits/faq/notion.md b/docs/content/toolkits/faq/notion.md
index 38a9faf84..e55548eda 100644
--- a/docs/content/toolkits/faq/notion.md
+++ b/docs/content/toolkits/faq/notion.md
@@ -14,4 +14,32 @@ No. Notion controls access by granting integrations access to specific pages and
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.
+## How do I set up the Notion webhook ingress endpoint?
+
+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.
+
+1. **Create the endpoint.**
+
+ ```bash
+ curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
+ -H "Content-Type: application/json" \
+ -d '{"toolkit_slug": "notion", "client_id": "<YOUR_NOTION_OAUTH_CLIENT_ID>"}'
+ ```
+
+ Save the returned `id` and `webhook_url`.
+
+2. **Paste the `webhook_url` into Notion** under your integration's Webhook settings. Notion will POST a verification token to the URL.
+
+3. **Read the token from Composio.**
+
+ ```bash
+ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
+ ```
+
+ The token is in `data.webhook_signing_secret`.
+
+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).
+
---