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: fix V3 payload format and add webhook subscriptions API references
Sushmithamalleshc722b2947a54
diff --git a/docs/content/docs/setting-up-triggers/index.mdx b/docs/content/docs/setting-up-triggers/index.mdxindex 72c91fab9..b342efb56 100644--- a/docs/content/docs/setting-up-triggers/index.mdx+++ b/docs/content/docs/setting-up-triggers/index.mdx@@ -91,26 +91,34 @@ The trigger instance uses the toolkit version configured during Composio initialWebhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.-1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)+1. Set your webhook URL in the [dashboard settings](https://platform.composio.dev?next_page=/settings/events) or via the [Webhook Subscriptions API](/reference/api-reference/webhooks)2. Build an endpoint that accepts POST requests with JSON payloads<Callout type="info">**Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.</Callout>+Composio delivers two event types via webhooks:++| Event type | Description |+|------------|-------------|+| `composio.trigger.message` | Trigger events from connected apps (all versions) |+| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |+### Webhook payload (V3)-New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:+New organizations receive V3 payloads by default. V3 uses a standardized `type` field (`composio.trigger.message`) and separates event metadata from the actual event data:```json{- "id": "wh_abc123",- "type": "github_commit_event",+ "id": "msg_abc123",+ "type": "composio.trigger.message","metadata": {- "triggerId": "ti_xyz789",- "connectedAccountId": "ca_def456",- "userId": "user-id-123435",- "toolkitSlug": "github"+ "trigger_slug": "GITHUB_COMMIT_EVENT",+ "trigger_id": "ti_xyz789",+ "connected_account_id": "ca_def456",+ "auth_config_id": "ac_xyz789",+ "user_id": "user-id-123435"},"data": {"commit_sha": "a1b2c3d",@@ -134,10 +142,11 @@ See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#weasync def webhook_handler(request: Request):payload = await request.json()- trigger_type = payload.get("type")+ metadata = payload.get("metadata", {})+ trigger_slug = metadata.get("trigger_slug")event_data = payload.get("data", {})- if trigger_type == "github_commit_event":+ if trigger_slug == "GITHUB_COMMIT_EVENT":commit = event_data.get("message")author = event_data.get("author")print(f"New commit by {author}: {commit}")@@ -154,8 +163,9 @@ type GitHubCommitEventData = { commit_sha: string; message: string; author: stri// ---cut---export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {const payload = req.body;+ const triggerSlug = payload.metadata?.trigger_slug;- if (payload.type === 'github_commit_event') {+ if (triggerSlug === 'GITHUB_COMMIT_EVENT') {const event: TriggerEvent<GitHubCommitEventData> = {type: payload.type,timestamp: payload.timestamp,diff --git a/docs/content/docs/setting-up-triggers/webhook-verification.mdx b/docs/content/docs/setting-up-triggers/webhook-verification.mdxindex 456e89bc8..c534516a3 100644--- a/docs/content/docs/setting-up-triggers/webhook-verification.mdx+++ b/docs/content/docs/setting-up-triggers/webhook-verification.mdx@@ -46,9 +46,9 @@ type Response = { status: (code: number) => { json: (data: any) => void; send: (// ---cut---const composio = new Composio({ apiKey: 'your-api-key' });-function handleWebhook(req: Request, res: Response) {+async function handleWebhook(req: Request, res: Response) {try {- const result = composio.triggers.verifyWebhook({+ const result = await composio.triggers.verifyWebhook({payload: req.body,signature: req.headers['webhook-signature'],id: req.headers['webhook-id'],@@ -158,13 +158,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep```json{- "id": "wh_abc123",- "type": "github_commit_event",+ "id": "msg_abc123",+ "type": "composio.trigger.message","metadata": {- "triggerId": "ti_xyz789",- "connectedAccountId": "ca_def456",- "userId": "user-id-123435",- "toolkitSlug": "github"+ "trigger_slug": "GITHUB_COMMIT_EVENT",+ "trigger_id": "ti_xyz789",+ "connected_account_id": "ca_def456",+ "auth_config_id": "ac_xyz789",+ "user_id": "user-id-123435"},"data": {"commit_sha": "a1b2c3d",@@ -211,8 +212,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep## Configuring your webhook URL and secret+You can configure webhooks via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks):+1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)2. Enter your publicly accessible webhook URL3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variableThe SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.++<Callout>+The Webhook Subscriptions API also supports event filtering — subscribe only to `composio.trigger.message`, `composio.connected_account.expired`, or both. See the [API reference](/reference/api-reference/webhooks) for details.+</Callout>diff --git a/docs/content/docs/triggers.mdx b/docs/content/docs/triggers.mdxindex 16c3f5703..acb15cb05 100644--- a/docs/content/docs/triggers.mdx+++ b/docs/content/docs/triggers.mdx@@ -17,8 +17,9 @@ There are two delivery types:1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)2. **Create** an active trigger scoped to a user's connected account-3. **Receive events**: Composio delivers payloads to your webhook endpoint-4. **Manage**: enable, disable, or delete triggers as needed+3. **Configure** your webhook endpoint so Composio knows where to deliver events+4. **Receive events**: Composio sends payloads to your endpoint+5. **Manage**: enable, disable, or delete triggers as needed<Accordions><Accordion title="What is a trigger type?">