@devries-cameron20 / composio-1 / commits / 0cb8a5293
Fork 0

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

Toolkit pages (e.g. /toolkits/slack) get triggers/tools server-side from Apollo and pull a per-toolkit FAQ from content/toolkits/faq/{slug}.md. The Slack FAQ already had a "How do I set up Slack event webhooks?" entry but it pointed at the legacy ingress URL; Notion had no webhook entry at all. - slack.md: rewrite the webhook setup answer to use the webhook_endpoints flow (POST /webhook_endpoints, PATCH signing secret, optional app_token, paste URL into Event Subscriptions). Lead with "Composio-managed credentials = nothing to do." Update the "Why aren't my Slack triggers working?" answer to reference the same flow. - notion.md: add a "How do I set up Notion webhook triggers?" entry with the same Composio-managed-vs-your-own split. Step 1 calls the schema endpoint as the source of truth for which credentials Notion needs, since I don't want to invent field names. - Both link to /docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint for the canonical reference. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 17:22 UTC 0cb8a5293d23b3a14f26f42043e8844d3a202648
2 files changed +80 -2
docs/content/toolkits/faq/notion.md
+38
@@ -14,4 +14,42 @@ 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 Notion webhook triggers?
18 +
19 +**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.
20 +
21 +**If you bring your own Notion integration**, configure a webhook endpoint once per integration. Step-by-step:
22 +
23 +1. **Discover what credentials Notion needs.** The schema endpoint is the source of truth for which fields you'll be asked to provide:
24 +
25 + curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=notion" \
26 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
27 +
28 +2. **Create the endpoint:**
29 +
30 + curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
31 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
32 + -H "Content-Type: application/json" \
33 + -d '{ "toolkit_slug": "notion", "client_id": "<YOUR_NOTION_CLIENT_ID>" }'
34 +
35 + Save the `id` and `webhook_url` from the response.
36 +
37 +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).
38 +
39 +4. **Store the credentials returned by the schema** (step 1) on the endpoint via `PATCH` — use the field names exactly as they came back:
40 +
41 + curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
42 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
43 + -H "Content-Type: application/json" \
44 + -d '{ "data": { "<FIELD_FROM_SCHEMA>": "<VALUE_FROM_NOTION>" } }'
45 +
46 +5. **Confirm the endpoint is verified:**
47 +
48 + curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
49 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
50 +
51 + A populated `verified_at` means Notion completed the verification handshake. You can now create Notion triggers on this OAuth app.
52 +
53 +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).
54 +
55 ---
docs/content/toolkits/faq/slack.md
+42 -2
@@ -24,7 +24,40 @@ Update the redirect URL in your Slack App under OAuth & Permissions → Redirect
24
25 ## How do I set up Slack event webhooks?
26
27 -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.
27 +**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.
28 +
29 +**If you bring your own Slack OAuth app**, configure a webhook endpoint once per OAuth app. Step-by-step:
30 +
31 +1. **Create the endpoint:**
32 +
33 + curl -X POST "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
34 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
35 + -H "Content-Type: application/json" \
36 + -d '{ "toolkit_slug": "slack", "client_id": "<YOUR_SLACK_CLIENT_ID>" }'
37 +
38 + Save the `id` and `webhook_url` from the response.
39 +
40 +2. **Store your signing secret on the endpoint** (Slack app → Basic Information → App Credentials → Signing Secret):
41 +
42 + curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
43 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
44 + -H "Content-Type: application/json" \
45 + -d '{ "data": { "webhook_signing_secret": "<SIGNING_SECRET>" } }'
46 +
47 +3. **For DMs, private channels, and reactions, also store an app-level token** (Slack app → Basic Information → App-Level Tokens, scope `authorizations:read`):
48 +
49 + curl -X PATCH "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
50 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>" \
51 + -H "Content-Type: application/json" \
52 + -d '{ "data": { "app_token": "xapp-..." } }'
53 +
54 +4. **Set Slack app → Event Subscriptions → Request URL** to the `webhook_url` from step 1. Composio responds to Slack's `url_verification` challenge automatically.
55 +
56 +5. **Subscribe to the events you need** under Event Subscriptions and save.
57 +
58 +If you're using the Slackbot integration, add the bot to the channels you want to monitor.
59 +
60 +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).
61
62 ## Why am I getting scope errors on Slack?
63
@@ -36,6 +69,13 @@ For the Slack toolkit, set `as_user=True` to post as the authenticated user. For
69
70 ## Why aren't my Slack triggers working?
71
39 -Provide the Verification Token or signing secret in the auth config so Composio can validate incoming events.
72 +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:
73 +
74 + curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
75 + -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"
76 +
77 +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.
78 +
79 +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.
80
81 ---