Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.
TypeScript agentic-aiagentsaiai-agentsaiagentsdeveloper-toolsfunction-callinggpt-4javascriptjsllmllmopsmcppythonremote-mcp-serverssetypescript
docs(changelog): add webhook triggers v2 announcement
Anshu Garge15d63146d70
diff --git a/docs/content/changelog/04-18-26-webhook-triggers-v2.mdx b/docs/content/changelog/04-18-26-webhook-triggers-v2.mdxnew file mode 100644index 000000000..9ced35a5f--- /dev/null+++ b/docs/content/changelog/04-18-26-webhook-triggers-v2.mdx@@ -0,0 +1,278 @@+---+title: "Webhook Triggers V2: Dedicated Endpoints, Signature Verification, and Per-User Authorization"+description: "New opt-in webhook pipeline with isolated endpoints per OAuth app, HMAC signature verification, private-channel support, and config-level filters. Fully backward compatible — existing triggers keep working with zero action required."+date: "2026-04-18"+---++We're rolling out **Webhook Triggers V2** — a new pipeline that gives each OAuth app its own dedicated webhook endpoint, verifies provider signatures at ingress, supports per-user authorization for private channels and DMs, and adds event-level config filters.++<Callout type="warn">+**No immediate action required.** Your existing webhook triggers continue to work exactly as they do today. V2 is opt-in per new trigger slug — you adopt it on your own schedule.+</Callout>++## Summary++| Change | Type | Action Required |+|--------|------|-----------------|+| New `webhook_endpoints` API | New Feature | No |+| V2 ingress URL (`/api/v3/webhook_ingress/...`) | New Feature | Only for V2 triggers |+| Signature verification at ingress | New Feature | Automatic on V2 |+| New Slack V2 trigger slugs | New Feature | Opt-in |+| Existing V1 triggers and URLs | Unchanged | No |+| One OAuth app per project (V2 only) | Constraint | Only when opting in |++---++## Why V2?++The V1 pipeline has a few long-standing gaps:++- **Shared ingress URL per toolkit.** Apps like Slack and HubSpot routed every customer's events through a single `/handle` endpoint. This made it impossible to rate-limit, meter, or isolate tenants cleanly at ingress.+- **No signature verification at the gateway.** Spoofed payloads were forwarded as if they were genuine.+- **No per-user authorization for app-level events.** Private channel messages and DMs couldn't be delivered safely — events flagged as requiring authorization were silently dropped.+- **No config-level filters.** Subscribing to messages in `#general` meant receiving every channel's messages and filtering client-side.+- **No lifecycle cleanup.** Deleting a trigger didn't unregister the provider-side webhook.++V2 addresses all of these while keeping V1 fully operational for existing triggers.++---++## What's New++### Dedicated webhook endpoints per OAuth app++V2 introduces a first-class `webhook_endpoints` resource. Each endpoint is keyed by `(toolkit_slug, project_id, client_id)` and exposes a unique ingress URL containing a random `we_*` identifier:++```+https://backend.composio.dev/api/v3/webhook_ingress/{toolkit_slug}/{we_xxx}/trigger_event+```++Because each OAuth app now has its own URL, we can:++- **Rate-limit and meter per endpoint** — noisy tenants no longer affect other customers+- **Fan out events only to trigger instances linked to this endpoint** — no cross-tenant leakage+- **Verify signatures with per-endpoint secrets** — missing or invalid signatures are rejected at the gateway+- **Attribute billing and observability per endpoint** — cleaner usage and health dashboards+- **Run deterministic teardown** — delete endpoint, rotate secrets, track verification status independently++### Signature verification at ingress++Apollo verifies HMAC-SHA256 (and provider-specific equivalents like Ed25519 for Svix or `token_match` for Telegram) on every V2 request using the signing secret you stored on the endpoint. Invalid payloads are rejected with `401` before any work is enqueued.++### Per-user authorization for private channels and DMs++For app-level toolkits with per-user visibility (Slack being the primary example), V2 uses an app-level token you provide (e.g., Slack `xapp-…` with the `authorizations:read` scope) to resolve exactly which connected users can see a given event. Only those users' triggers fire.++This unlocks triggers like `SLACK_DIRECT_MESSAGE_RECEIVED` that were not safely deliverable on V1.++### Config-level filters++V2 triggers support rich config filters applied at match-time against the event payload:++```json+{+ "trigger_config": {+ "channel_id": "C_SUPPORT",+ "is_bot_message": "false",+ "is_thread_reply": "false"+ }+}+```++You only receive events that match the filter — no client-side filtering required.++### Handshake + lifecycle support++Provider handshakes (Slack `url_verification`, Asana `X-Hook-Secret`, Outlook validation tokens, etc.) are handled centrally in Apollo based on each toolkit's webhook spec. Provider-side webhooks are also torn down when you delete a user-level trigger.++---++## New API Endpoints++All endpoints live under `/api/v3/webhook_endpoints` and require your project API key (`x-api-key`).++| Method | Endpoint | Purpose |+|--------|----------|---------|+| `GET` | `/api/v3/webhook_endpoints/schema?toolkit_slug={slug}` | Discover required fields (e.g. `webhook_signing_secret`, `app_token` for Slack) |+| `POST` | `/api/v3/webhook_endpoints` | Create (or fetch) an endpoint. Idempotent per `(toolkit_slug, project, client_id)` |+| `GET` | `/api/v3/webhook_endpoints` | List endpoints in the current project |+| `GET` | `/api/v3/webhook_endpoints/{id}` | Get details, including `verified_at` (set after handshake) |+| `POST` | `/api/v3/webhook_endpoints/{id}` | Configure `setup_data` (full replace) |+| `PATCH` | `/api/v3/webhook_endpoints/{id}` | Rotate or add a single secret without touching the others |+| `DELETE` | `/api/v3/webhook_endpoints/{id}` | Soft-delete the endpoint |++And the new ingress route (this is the URL you paste into your provider's dashboard):++| Method | Endpoint |+|--------|----------|+| `POST` | `/api/v3/webhook_ingress/{toolkit_slug}/{webhook_endpoint_nano_id}/trigger_event` |++The V1 route at `/api/v3/trigger_instances/{toolkit_slug}/{project_id}/handle` is **not deprecated** and keeps working for existing triggers.++---++## Adopting V2 (Slack example)++V2 becomes available toolkit-by-toolkit. **Slack is the first production rollout.** The flow below applies to every toolkit we migrate next.++### 1. Check required fields for the toolkit++```bash+curl "https://backend.composio.dev/api/v3/webhook_endpoints/schema?toolkit_slug=slack" \+ -H "x-api-key: YOUR_API_KEY"+```++### 2. Create the endpoint++```bash+curl -X POST "https://backend.composio.dev/api/v3/webhook_endpoints" \+ -H "x-api-key: YOUR_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "toolkit_slug": "slack",+ "client_id": "<YOUR_SLACK_CLIENT_ID>"+ }'+```++The response contains a `webhook_url`. This call is idempotent — calling it again with the same parameters returns the existing endpoint.++### 3. Store your signing secret **before** switching the dashboard URL++```bash+curl -X PATCH "https://backend.composio.dev/api/v3/webhook_endpoints/<ENDPOINT_ID>" \+ -H "x-api-key: YOUR_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "data": {+ "webhook_signing_secret": "<YOUR_SIGNING_SECRET>"+ }+ }'+```++<Callout type="warn">+**Order matters.** If you paste the V2 URL into Slack before the signing secret is stored, every event fails signature verification with HTTP `400`, and Slack may disable the endpoint after ~36 hours of failures. Always: **store secret first, then switch the URL**.+</Callout>++### 4. Switch your Slack app's Event Subscriptions URL to the V2 `webhook_url`++Slack sends a `url_verification` challenge, Apollo responds automatically, and `verified_at` is set on the endpoint.++### 5. (Optional) Add the app-level token for private channel and DM support++```bash+curl -X PATCH "https://backend.composio.dev/api/v3/webhook_endpoints/<ENDPOINT_ID>" \+ -H "x-api-key: YOUR_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "data": {+ "app_token": "xapp-..."+ }+ }'+```++To generate the token: in your Slack app, go to **Basic Information → App-Level Tokens**, click **Generate Token and Scopes**, and add the `authorizations:read` scope.++### 6. Create trigger instances using the new V2 slugs++| V1 slug (still works) | V2 equivalent (opt-in) | V2 extras |+|---|---|---|+| `SLACK_RECEIVE_MESSAGE` | `SLACK_CHANNEL_MESSAGE_RECEIVED` | `channel_id`, `is_bot_message`, `is_thread_reply` filters |+| `SLACK_RECEIVE_DIRECT_MESSAGE` | `SLACK_DIRECT_MESSAGE_RECEIVED` | Per-user authorization via `app_token` |++```bash+curl -X POST "https://backend.composio.dev/api/v3/trigger_instances/SLACK_CHANNEL_MESSAGE_RECEIVED/upsert" \+ -H "x-api-key: YOUR_API_KEY" \+ -H "Content-Type: application/json" \+ -d '{+ "connected_account_id": "<CONNECTED_ACCOUNT_ID>",+ "trigger_config": {+ "channel_id": "C_SUPPORT",+ "is_bot_message": "false"+ }+ }'+```++<Callout type="info">+If you attempt to create a V2-only slug without first creating a `webhook_endpoint`, Apollo returns `400` with a `suggestedFix` pointing you to `POST /api/v3/webhook_endpoints`.+</Callout>++---++## One OAuth App = One Project (important)++The `webhook_endpoints` table keys uniqueness on `(toolkit_slug, project_id, client_id)`. More importantly, **the provider dashboard (Slack, HubSpot, Linear, etc.) only accepts one callback URL per OAuth app.**++<Callout type="warn">+On V2, each OAuth app (`client_id`) can effectively be attached to a single Composio project. If you currently share one OAuth app across multiple projects or organizations on V1, you must choose one project to own that OAuth app when moving it to V2.+</Callout>++### Your options when a shared OAuth app wants V2 features++1. **Consolidate** — pick a single project to own the OAuth app and run V2 there. Other projects can keep using the same OAuth app on V1 with no changes.+2. **Create separate OAuth apps** — one per project that needs V2. This is the recommended long-term approach.++### Why this constraint?++- **Per-project rate limits.** A shared OAuth app today means one noisy project can consume the entire OAuth app's ingress capacity. Scoping the endpoint to a single project gives every project its own budget.+- **Clean fan-out.** Events are matched only to trigger instances on the project that owns the endpoint — no accidental cross-project delivery, no reference counting.+- **Tenant-scoped security.** Signing secrets and app-level tokens live on a single project's endpoint row. There is no shared endpoint across projects or organizations that any tenant could read from or corrupt.+- **Accurate billing and metering.** Webhook ingress volume is attributed unambiguously to the owning project.+- **Deterministic lifecycle.** Teardown, rotation, and verification are unambiguous per-project operations.++Again — **you are never forced to move to V2**. The shared V1 endpoint for existing OAuth apps keeps running indefinitely. You only encounter this constraint when you actively opt a project into V2 for a given OAuth app.++---++## Backward Compatibility++<Callout type="warn">+**No existing trigger is touched by this release.** No URLs to change, no API changes, no data migrations on our end that touch your data.+</Callout>++### What Continues to Work++- All existing trigger slugs on every toolkit (for Slack: `SLACK_RECEIVE_MESSAGE`, `SLACK_RECEIVE_DIRECT_MESSAGE`, `SLACK_RECEIVE_GROUP_MESSAGE`, `SLACKBOT_*`, and every other legacy slug)+- The V1 ingress URL pattern (`/api/v3/trigger_instances/{toolkit}/{project_id}/handle`)+- Existing `POST /trigger_instances/{slug}/upsert` setup flow — create auth_config, upsert trigger, done+- All V1/V2/V3 webhook payload versions+- Custom OAuth apps that share a `client_id` across projects — they continue working on V1 with no changes++### What's Opt-In++- Creating a `webhook_endpoint`+- Switching your provider dashboard URL to the V2 ingress URL+- Using new V2-only trigger slugs++---++## Rollout++- **2026-04-18 (today):** Webhook endpoints APIs, V2 ingress, signature verification, and the new Slack V2 slugs (`SLACK_CHANNEL_MESSAGE_RECEIVED`, `SLACK_DIRECT_MESSAGE_RECEIVED`) are live in production.+- **Next:** We'll migrate HubSpot, Linear, and other app-level toolkits using the same pattern. Each migration ships with its own changelog entry.+- **V1 sunset:** No date. V1 ingress and all V1 slugs continue to work indefinitely.++---++## FAQ++**Do I have to change my Slack Event Subscriptions URL?**+No. If you're happy with V1 behavior, leave it as-is. Only switch when you want V2 features.++**Will my existing `SLACK_RECEIVE_MESSAGE` triggers keep firing?**+Yes — with no change. They route through V1 exactly as they do today.++**Can I mix V1 and V2 triggers under the same OAuth app?**+Yes, on the same project. Once the dashboard URL is on V2, all events from that OAuth app flow through V2 ingress. Trigger instances on V1 slugs still match and fire; instances on V2 slugs additionally get filtering and per-user authorization.++**My OAuth app is shared across 3 projects. What happens if I flip the URL to a V2 endpoint on one project?**+Events from that OAuth app start flowing to the V2 endpoint on that one project. The other two projects stop receiving events from that app, because the provider only has one URL to send to. Either consolidate to one project, or create separate OAuth apps for the other projects.++**What happens if my signing secret is wrong or missing?**+Apollo rejects incoming requests with `401`. The provider retries with backoff and may disable your endpoint after repeated failures (~36h for Slack). Always store the secret before flipping the URL.++---++## Need Help?++- [Discord community](https://discord.gg/composio)+- Email: [email protected]