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(toolkits): add webhook-endpoint setup to Slack and Notion FAQs

Anshu Garg0cb8a5293d23
diff --git a/docs/content/toolkits/faq/notion.md b/docs/content/toolkits/faq/notion.md
index 38a9faf84..98d6f9ec6 100644
--- a/docs/content/toolkits/faq/notion.md
+++ b/docs/content/toolkits/faq/notion.md
@@ -14,4 +14,42 @@ 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 Notion webhook triggers?
+
+**If you use Composio-managed Notion credentials**, nothing to set up — the webhook endpoint is already provisioned for your project. Create the trigger and you're done.
+
+**If you bring your own Notion integration**, configure a webhook endpoint once per integration. Step-by-step:
+
+1. **Discover what credentials Notion needs.** The schema endpoint is the source of truth for which fields you'll be asked to provide:
+
+ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=notion" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
+
+2. **Create the endpoint:**
+
+ 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_CLIENT_ID>" }'
+
+ Save the `id` and `webhook_url` from the response.
+
+3. **Add the `webhook_url`** from step 2 to your Notion integration's **Webhooks** settings (in the integration's configuration page on Notion's developer dashboard).
+
+4. **Store the credentials returned by the schema** (step 1) on the endpoint via `PATCH` — use the field names exactly as they came back:
+
+ curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
+ -H "Content-Type: application/json" \
+ -d '{ "data": { "<FIELD_FROM_SCHEMA>": "<VALUE_FROM_NOTION>" } }'
+
+5. **Confirm the endpoint is verified:**
+
+ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
+
+ A populated `verified_at` means Notion completed the verification handshake. You can now create Notion triggers on this OAuth app.
+
+For the full reference (PATCH vs POST update semantics, rotating credentials, listing endpoints), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
+
---
diff --git a/docs/content/toolkits/faq/slack.md b/docs/content/toolkits/faq/slack.md
index 5681cda1f..70e347d22 100644
--- a/docs/content/toolkits/faq/slack.md
+++ b/docs/content/toolkits/faq/slack.md
@@ -24,7 +24,40 @@ Update the redirect URL in your Slack App under OAuth & Permissions → Redirect
## How do I set up Slack event webhooks?
-Enable Event Subscriptions in your Slack app. Set the Request URL to `https://backend.composio.dev/api/v3.1/trigger_instances/slack/default/handle`. Add events (e.g., `reaction_added`) to Subscribe to Bot Events and save. If using the Slackbot integration, add the bot to the channels you want to monitor.
+**If you use Composio-managed Slack credentials**, nothing to set up — the webhook endpoint is already provisioned for your project. Create the trigger and you're done.
+
+**If you bring your own Slack OAuth app**, configure a webhook endpoint once per OAuth app. Step-by-step:
+
+1. **Create the endpoint:**
+
+ 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": "slack", "client_id": "<YOUR_SLACK_CLIENT_ID>" }'
+
+ Save the `id` and `webhook_url` from the response.
+
+2. **Store your signing secret on the endpoint** (Slack app → Basic Information → App Credentials → Signing Secret):
+
+ curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
+ -H "Content-Type: application/json" \
+ -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'
+
+3. **For DMs, private channels, and reactions, also store an app-level token** (Slack app → Basic Information → App-Level Tokens, scope `authorizations:read`):
+
+ curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
+ -H "Content-Type: application/json" \
+ -d '{ "data": { "app_token": "xapp-..." } }'
+
+4. **Set Slack app → Event Subscriptions → Request URL** to the `webhook_url` from step 1. Composio responds to Slack's `url_verification` challenge automatically.
+
+5. **Subscribe to the events you need** under Event Subscriptions and save.
+
+If you're using the Slackbot integration, add the bot to the channels you want to monitor.
+
+For the full reference (PATCH vs POST update semantics, listing endpoints, troubleshooting), see [Configuring the webhook endpoint](https://docs.composio.dev/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint).
## Why am I getting scope errors on Slack?
@@ -36,6 +69,13 @@ For the Slack toolkit, set `as_user=True` to post as the authenticated user. For
## Why aren't my Slack triggers working?
-Provide the Verification Token or signing secret in the auth config so Composio can validate incoming events.
+If you bring your own Slack OAuth app, the most common cause is a missing or wrong **signing secret on the webhook endpoint** — every inbound request fails signature verification with `400`, and Slack auto-disables the URL after about 36 hours of consecutive failures. Confirm the endpoint is set up correctly:
+
+ curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
+ -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
+
+Look for an endpoint with your `client_id` and a populated `verified_at`. If `verified_at` is null, the URL hasn't completed Slack's `url_verification` handshake yet — re-save the URL on Slack app → Event Subscriptions. If you don't see an endpoint at all, follow [How do I set up Slack event webhooks?](#how-do-i-set-up-slack-event-webhooks) above.
+
+For DMs, private channels, or reactions, also confirm the endpoint has an `app_token` set. See [Triggers troubleshooting](https://docs.composio.dev/docs/troubleshooting/triggers) for the full list of failure modes.
---