@devries-cameron20 / composio-1 / commits / c722b2947
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: fix V3 payload format and add webhook subscriptions API references

- Fix V3 type field to "composio.trigger.message" with trigger_slug in metadata - Fix metadata fields to match actual API (snake_case, correct field set) - Update example handlers to route on metadata.trigger_slug - Add await to TS verifyWebhook() (async since SDK 0.6.0) - Add event types table (composio.trigger.message, composio.connected_account.expired) - Reference Webhook Subscriptions API in webhook setup steps - Add "Configure webhook endpoint" step to trigger lifecycle Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 9, 2026 at 15:52 UTC c722b2947a548d8c0da5b4e7cd911ae0f17c1a83
3 files changed +39 -21
docs/content/docs/setting-up-triggers/index.mdx
+21 -11
@@ -91,26 +91,34 @@ The trigger instance uses the toolkit version configured during Composio initial
91
92 Webhooks are the recommended way to receive trigger events in production. Composio sends a POST request to your endpoint whenever an event fires.
93
94 -1. Set your webhook URL in [Event & Trigger settings](https://platform.composio.dev?next_page=/settings/events)
94 +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)
95 2. Build an endpoint that accepts POST requests with JSON payloads
96
97 <Callout type="info">
98 **Local development:** Use [ngrok](https://ngrok.com) or [webhook.site](https://webhook.site) to expose your local server for testing.
99 </Callout>
100
101 +Composio delivers two event types via webhooks:
102 +
103 +| Event type | Description |
104 +|------------|-------------|
105 +| `composio.trigger.message` | Trigger events from connected apps (all versions) |
106 +| `composio.connected_account.expired` | OAuth2 connection expired and needs re-authentication (V3 only) |
107 +
108 ### Webhook payload (V3)
109
103 -New organizations receive V3 payloads by default. The payload separates event metadata from the actual event data:
110 +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:
111
112 ```json
113 {
107 - "id": "wh_abc123",
108 - "type": "github_commit_event",
114 + "id": "msg_abc123",
115 + "type": "composio.trigger.message",
116 "metadata": {
110 - "triggerId": "ti_xyz789",
111 - "connectedAccountId": "ca_def456",
112 - "userId": "user-id-123435",
113 - "toolkitSlug": "github"
117 + "trigger_slug": "GITHUB_COMMIT_EVENT",
118 + "trigger_id": "ti_xyz789",
119 + "connected_account_id": "ca_def456",
120 + "auth_config_id": "ac_xyz789",
121 + "user_id": "user-id-123435"
122 },
123 "data": {
124 "commit_sha": "a1b2c3d",
@@ -134,10 +142,11 @@ See [webhook payload versions](/docs/setting-up-triggers/webhook-verification#we
142 async def webhook_handler(request: Request):
143 payload = await request.json()
144
137 - trigger_type = payload.get("type")
145 + metadata = payload.get("metadata", {})
146 + trigger_slug = metadata.get("trigger_slug")
147 event_data = payload.get("data", {})
148
140 - if trigger_type == "github_commit_event":
149 + if trigger_slug == "GITHUB_COMMIT_EVENT":
150 commit = event_data.get("message")
151 author = event_data.get("author")
152 print(f"New commit by {author}: {commit}")
@@ -154,8 +163,9 @@ type GitHubCommitEventData = { commit_sha: string; message: string; author: stri
163 // ---cut---
164 export default async function webhookHandler(req: NextApiRequest, res: NextApiResponse) {
165 const payload = req.body;
166 + const triggerSlug = payload.metadata?.trigger_slug;
167
158 - if (payload.type === 'github_commit_event') {
168 + if (triggerSlug === 'GITHUB_COMMIT_EVENT') {
169 const event: TriggerEvent<GitHubCommitEventData> = {
170 type: payload.type,
171 timestamp: payload.timestamp,
docs/content/docs/setting-up-triggers/webhook-verification.mdx
+15 -8
@@ -46,9 +46,9 @@ type Response = { status: (code: number) => { json: (data: any) => void; send: (
46 // ---cut---
47 const composio = new Composio({ apiKey: 'your-api-key' });
48
49 -function handleWebhook(req: Request, res: Response) {
49 +async function handleWebhook(req: Request, res: Response) {
50 try {
51 - const result = composio.triggers.verifyWebhook({
51 + const result = await composio.triggers.verifyWebhook({
52 payload: req.body,
53 signature: req.headers['webhook-signature'],
54 id: req.headers['webhook-id'],
@@ -158,13 +158,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
158
159 ```json
160 {
161 - "id": "wh_abc123",
162 - "type": "github_commit_event",
161 + "id": "msg_abc123",
162 + "type": "composio.trigger.message",
163 "metadata": {
164 - "triggerId": "ti_xyz789",
165 - "connectedAccountId": "ca_def456",
166 - "userId": "user-id-123435",
167 - "toolkitSlug": "github"
164 + "trigger_slug": "GITHUB_COMMIT_EVENT",
165 + "trigger_id": "ti_xyz789",
166 + "connected_account_id": "ca_def456",
167 + "auth_config_id": "ac_xyz789",
168 + "user_id": "user-id-123435"
169 },
170 "data": {
171 "commit_sha": "a1b2c3d",
@@ -211,8 +212,14 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
212
213 ## Configuring your webhook URL and secret
214
215 +You can configure webhooks via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks):
216 +
217 1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)
218 2. Enter your publicly accessible webhook URL
219 3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
220
221 The SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.
222 +
223 +<Callout>
224 +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.
225 +</Callout>
docs/content/docs/triggers.mdx
+3 -2
@@ -17,8 +17,9 @@ There are two delivery types:
17
18 1. **Discover** available trigger types for a toolkit (e.g., `GITHUB_COMMIT_EVENT`)
19 2. **Create** an active trigger scoped to a user's connected account
20 -3. **Receive events**: Composio delivers payloads to your webhook endpoint
21 -4. **Manage**: enable, disable, or delete triggers as needed
20 +3. **Configure** your webhook endpoint so Composio knows where to deliver events
21 +4. **Receive events**: Composio sends payloads to your endpoint
22 +5. **Manage**: enable, disable, or delete triggers as needed
23
24 <Accordions>
25 <Accordion title="What is a trigger type?">