Configuring webhook endpoints

Some toolkits — currently Slack, with more arriving on the same model — deliver events at the OAuth-app level rather than per-user. For these toolkits, you need to create a webhook_endpoint once per OAuth app, store the provider's signing secret on it, and point the provider's app dashboard at the URL Composio returns.

This is the only piece of trigger setup that's not automatic. Once it's done, creating triggers and subscribing to events work the same as for any other toolkit.

What a webhook endpoint is

A webhook_endpoint is a project-scoped resource keyed by (toolkit_slug, project_id, client_id). It exposes one ingress URL containing a random we_* identifier:

https://backend.composio.dev/api/v3.1/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event

Provider events posted to this URL are verified at ingress against the signing secret stored on the endpoint, then fanned out only to trigger instances on that endpoint's project. Unsigned or tampered requests are rejected before any trigger fires.

End-to-end setup (Slack)

The flow below uses Slack because it's the first toolkit on V2. Substitute slack with any other V2 toolkit slug as more come online — the API surface is identical.

curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/schema?toolkit_slug=slack" \
  -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"

{
  "toolkit_slug": "slack",
  "setup_fields": {
    "webhook_signing_secret": {
      "display_name": "Signing Secret",
      "description": "Webhook request signing secret from your Slack app dashboard",
      "is_required": true,
      "is_secret": true
    },
    "app_token": {
      "display_name": "App-Level Token",
      "description": "Slack xapp- token with authorizations:read scope for event authorization",
      "is_required": true,
      "is_secret": true
    }
  }
}

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>"
  }'

{
  "id": "we_abc123",
  "toolkit_slug": "slack",
  "client_id": "<YOUR_SLACK_CLIENT_ID>",
  "webhook_url": "https://backend.composio.dev/api/v3.1/webhook_ingress/slack/we_abc123/trigger_event",
  "data": null,
  "created_at": "2026-04-24T10:00:00.000Z"
}

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": "<YOUR_SLACK_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": {
      "app_token": "xapp-..."
    }
  }'

curl "https://backend.composio.dev/api/v3.1/webhook_endpoints/<ENDPOINT_ID>" \
  -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"

Updating an endpoint

Use PATCH to update one field at a time (e.g. rotate just the 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": "<NEW_SECRET>" } }'

Use POST to replace data wholesale — any field you don't include is cleared:

curl -X POST "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": "<NEW_SECRET>", "app_token": "<NEW_APP_TOKEN>" } }'

The webhook_url itself is immutable — it's tied to the endpoint's we_* id for the lifetime of the endpoint. Rotating the signing secret on the provider side is a PATCH on the existing endpoint, not a new endpoint.

Listing endpoints

curl "https://backend.composio.dev/api/v3.1/webhook_endpoints" \
  -H "x-api-key: <YOUR_COMPOSIO_API_KEY>"

Returns every endpoint in the current project with verified_at populated for the ones that have completed the handshake. Use this when you're operating across many OAuth apps and want a quick health view.

Migrating from V1

If you already have V1 trigger instances running, your existing setup is unchanged — V1 ingress URLs (/api/v3/trigger_instances/{toolkit}/{project_id}/handle) are not deprecated and every legacy slug (SLACK_RECEIVE_*, SLACKBOT_*, etc.) keeps routing through V1.

You only need to set up a V2 webhook endpoint in two cases:

1. You want to use a V2 trigger slug. For Slack, that's SLACK_CHANNEL_MESSAGE_RECEIVED, SLACK_DIRECT_MESSAGE_RECEIVED, or SLACK_MESSAGE_REACTION_ADDED. Without an endpoint, the upsert call returns 400.
2. You want to consolidate an OAuth app onto V2. Pick the project that should own the OAuth app on V2, set up an endpoint there, and update the provider's callback URL.

Even outside these cases, moving an OAuth app to V2 is recommended for the security wins — ingress signature verification, project-scoped fan-out, and per-user authorization for app-level events. See the V2 announcement for the full migration walkthrough and the V1 → V2 slug mapping for Slack.

What to read next