Webhook Triggers V2
Webhook Triggers V2 introduces a first-classwebhook_endpoints resource with a dedicated ingress URL per OAuth app. V2 is opt-in and scoped to new trigger slugs — existing V1 triggers, URLs, and payload formats are unchanged.
Summary
What’s in V2
Dedicated endpoint per OAuth app. Eachwebhook_endpoint is keyed by (toolkit_slug, project_id, client_id) and exposes its own URL containing a random we_* identifier:
/handle URL per toolkit. Events arriving on a V2 URL are fanned out only to trigger instances on that endpoint’s project.
Signature verification at ingress. Composio cryptographically verifies every V2 request against the signing secret stored on the endpoint, using HMAC-SHA256, Ed25519, or shared-token matching depending on the toolkit. Unsigned or tampered payloads are rejected, so third parties cannot spoof events onto your triggers. For providers that sign a request timestamp (e.g. Slack), replay protection additionally rejects requests whose timestamp falls outside the allowed skew window.
Per-user authorization for app-level events. On toolkits with per-user visibility — Slack being the first — V2 uses an app-level token (for Slack, an xapp-… token with authorizations:read) to resolve which connected users are authorized for a given event, so only those users’ triggers fire. This underpins a new class of triggers for private channels, direct messages, and other per-recipient events, each routed only to the user the event was intended for.
Automatic handshakes and cleanup. Composio responds to provider verification challenges — Slack url_verification, Asana X-Hook-Secret, Outlook validation tokens, and so on — so callback URLs verify without any custom code. User-level webhooks are also deregistered on the provider side when the trigger is deleted.
API reference
All endpoints require a project API key (x-api-key).
Provider events are posted to:
Migration walkthrough (Slack)
Slack is the first toolkit on V2. The same flow applies to every toolkit added later.1. Discover required fields
2. Create the endpoint
id (used as ENDPOINT_ID in the next steps) and webhook_url (the URL you’ll paste into your Slack app dashboard in step 5). The call is idempotent — calling it again with the same toolkit_slug and client_id returns the existing endpoint.
3. Store the signing secret
4. Add an app-level token for private-scope events
The app-level token is what lets Composio resolve per-user authorization for Slack’s private-scope events.SLACK_DIRECT_MESSAGE_RECEIVEDalways requires it.SLACK_CHANNEL_MESSAGE_RECEIVEDrequires it for events from private channels and multi-person DMs; public-channel messages are delivered without it.
authorizations:read.
5. Point your Slack app at the V2 URL
Set Event Subscriptions → Request URL in your Slack app to thewebhook_url returned in step 2. Composio verifies the endpoint with Slack automatically — no extra action needed on your side.
6. Create V2 trigger instances
Three new Slack triggers go live on V2 today, with more to follow on V2 — both for Slack and for other toolkits. The table below maps your existing V1 slugs to the new V2 equivalents:Heads up: OAuth apps are project-scoped on V2
The provider dashboard accepts only one callback URL per OAuth app, and each V2 URL resolves to exactly one project — so a single OAuth app cannot feed multiple projects on V2. The signing secret also lives on the endpoint, so the reverse holds too: two different OAuth apps cannot share one V2 endpoint — Composio only verifies signatures against the secret stored on that endpoint, so requests signed by a different OAuth app would be rejected. In return, every project graduates to a first-class webhook tenant on V2 — with its own:- Ingress rate-limit and backpressure budget
- Clean fan-out — events reach only that project’s trigger instances
- Signing secret and app-level token, scoped to this project alone
- Per-project metering and billing
Backward compatibility
Everything you have today keeps working — same URLs, same trigger slugs, same payload shapes, no data migration.- The V1 ingress URL (
/api/v3/trigger_instances/{toolkit}/{project_id}/handle) is not deprecated. - Every existing trigger slug —
SLACK_RECEIVE_*,SLACKBOT_*, and the equivalent legacy slugs on other toolkits — continues to route through V1.
- You want to use one of the new V2 trigger slugs (e.g.
SLACK_CHANNEL_MESSAGE_RECEIVED,SLACK_DIRECT_MESSAGE_RECEIVED). A V2 endpoint is required at setup; without one, the upsert returns400. - You want to move an OAuth app that’s currently shared across multiple projects or organizations onto V2. Pick the project that should own it on V2 and set up an endpoint there, or register separate OAuth apps per project (see Heads up: OAuth apps are project-scoped on V2).