@devries-cameron20 / composio-1 / commits / 649d92394
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(triggers): drop webhook-endpoint troubleshooting; note re-handshake rejection

troubleshooting/triggers.mdx - Remove the "Webhook endpoint issues" section. Bloated a generic troubleshooting page with feature-specific content that's also drift-prone — already-known failure modes (signing secret missing, verified_at null, missing app_token, replay-window) are surfaced during setup in the Configuring section's warn callouts. creating-triggers.mdx - Add one short sentence to the upsides paragraph noting that repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped by a forged handshake. Subtle placement (no callout, no heading) since this is a security guarantee customers should know about but don't have to act on. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Anshu Garg committed May 7, 2026 at 20:57 UTC 649d92394460cc1bc2fa8b557c920bc575fc988a
2 files changed +1 -11
docs/content/docs/setting-up-triggers/creating-triggers.mdx
+1 -1
@@ -96,7 +96,7 @@ Each OAuth app you bring gets its own ingress URL within a project:
96 https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event
97 ```
98
99 -A single OAuth app can serve at most one Composio project, since providers accept only one callback URL per OAuth app and each ingress URL routes to a single project. The upside: every project becomes its own webhook tenant with isolated ingress rate limits, its own signing secret and app-level token, clean fan-out (events only reach that project's triggers), and per-project metering.
99 +A single OAuth app can serve at most one Composio project, since providers accept only one callback URL per OAuth app and each ingress URL routes to a single project. The upside: every project becomes its own webhook tenant with isolated ingress rate limits, its own signing secret and app-level token, clean fan-out (events only reach that project's triggers), and per-project metering. Repeat verification handshakes are rejected after the endpoint is verified, so the signing secret can't be silently swapped.
100
101 Provider events are verified at ingress against the endpoint's signing secret before any trigger fires — HMAC-SHA256 for Slack, Ed25519 or shared-token matching for others. For providers that sign a request timestamp, replay protection additionally rejects requests outside the allowed skew window. Unsigned or tampered requests get a `400` at ingress, so third parties cannot spoof events onto your triggers.
102
docs/content/docs/troubleshooting/triggers.mdx
-10
@@ -14,16 +14,6 @@ Check the error message — the connected account might not have sufficient perm
14 - **Trigger status**: Verify the trigger is enabled, not disabled.
15 - **Logs**: Check the [trigger logs](https://platform.composio.dev?next_page=/logs/triggers) in the dashboard for delivery attempts and errors.
16
17 -## Webhook endpoint issues
18 -
19 -These only apply to triggers whose `requires_webhook_endpoint_setup` flag is `true` — see [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint). With Composio-managed OAuth apps the endpoint is provisioned automatically, so these don't apply.
20 -
21 -- **`400` on trigger upsert.** The OAuth app's `client_id` doesn't have a webhook endpoint in this project. Create one via `POST /api/v3.1/webhook_endpoints`.
22 -- **`400` on every provider request.** The signing secret on the [webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) is missing or wrong. `PATCH` the endpoint with the secret before pointing the provider's dashboard at the URL — Slack auto-disables endpoints after ~36 hours of consecutive failures.
23 -- **`verified_at` is null on the endpoint.** The provider hasn't completed the URL verification handshake yet. Re-save the URL in the provider's dashboard; for Slack, click **Save Changes** on Event Subscriptions.
24 -- **DMs / private channels / reactions don't fire on Slack.** The `app_token` is missing on the endpoint. `PATCH` the endpoint with an `xapp-` token that has the `authorizations:read` scope. See [Configuring the webhook endpoint](/docs/setting-up-triggers/creating-triggers#configuring-the-webhook-endpoint) for which Slack triggers require this.
25 -- **Replay-window rejections.** For providers that sign a timestamp (Slack), requests outside the allowed skew window are rejected. Make sure the system posting the events isn't replaying old payloads.
26 -
17 ## Type errors with trigger payloads
18
19 Use `getType()` / `get_type()` to inspect the exact payload schema for a trigger type. This shows you the fields and types you should expect.