@devries-cameron20 / composio Mirror · read-only / commits / f479c9fde
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.

Mirrored from https://github.com/Camo67/composio.git

Synced Nov 22, 09:30 UTC

docs: polish webhook verification page

- Remove hardcoded API keys, use Composio() without args - Fix manual verification examples to actually compare signatures - Fix V1/V2 payload examples to match SDK schemas - Collapse payload versions into tabs - Remove redundant headings and boilerplate - Add webhook secret callout - Trim prose, let code speak Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Sushmithamallesh committed Feb 10, 2026 at 07:56 UTC f479c9fdeb7b24956a42035cce3a7be71010b6aa
1 file changed +85 -118
docs/content/docs/setting-up-triggers/webhook-verification.mdx
+85 -118
@@ -4,110 +4,67 @@ description: Verify webhook signatures to ensure payloads are authentic
4 keywords: [webhook, verification, signature, HMAC, security]
5 ---
6
7 -Composio signs every webhook request so you can verify the payload was sent by Composio and hasn't been tampered with. Always verify signatures in production.
7 +Composio signs every webhook request. Always verify signatures in production to ensure payloads are authentic.
8
9 -## Using verifyWebhook()
9 +## SDK verification
10
11 -The SDK provides a built-in method that handles signature verification and payload parsing. It auto-detects the webhook payload version (V1, V2, or V3) and throws an error if verification fails.
11 +The SDK handles signature verification, payload parsing, and version detection (V1, V2, V3).
12 +
13 +<Callout>
14 +Get your webhook secret from [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook) and store it as `COMPOSIO_WEBHOOK_SECRET`.
15 +</Callout>
16
17 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
18 <Tab value="Python">
19 ```python
16 -from composio import Composio
17 -from flask import Flask, request, jsonify
18 -
19 -app = Flask(__name__)
20 -composio = Composio(api_key="your-api-key")
21 -
22 -@app.route("/webhook", methods=["POST"])
23 -def webhook_handler():
24 - try:
25 - result = composio.triggers.verify_webhook(
26 - payload=request.get_data(as_text=True),
27 - signature=request.headers.get("webhook-signature", ""),
28 - id=request.headers.get("webhook-id", ""),
29 - timestamp=request.headers.get("webhook-timestamp", ""),
30 - secret=os.getenv("COMPOSIO_WEBHOOK_SECRET", ""),
31 - )
32 -
33 - # result.version: "V3", "V2", or "V1"
34 - # result.payload: parsed, version-normalized payload
35 - print(f"Verified {result.version} payload: {result.payload}")
36 - return jsonify({"status": "ok"})
37 - except Exception as e:
38 - return jsonify({"error": "Invalid signature"}), 401
20 +try:
21 + result = composio.triggers.verify_webhook(
22 + id=request.headers.get("webhook-id", ""),
23 + payload=request.get_data(as_text=True),
24 + signature=request.headers.get("webhook-signature", ""),
25 + timestamp=request.headers.get("webhook-timestamp", ""),
26 + secret=os.getenv("COMPOSIO_WEBHOOK_SECRET", ""),
27 + )
28 + # result.version, result.payload, result.raw_payload
29 +except Exception:
30 + return {"error": "Invalid signature"}, 401
31 ```
32 </Tab>
33 <Tab value="TypeScript">
34 ```typescript
35 import { Composio } from '@composio/core';
44 -type Request = { body: string; headers: Record<string, string> };
45 -type Response = { status: (code: number) => { json: (data: any) => void; send: (data: string) => void }; json: (data: any) => void };
36 +const composio = new Composio();
37 +const req = { headers: {} as Record<string, string>, body: '' };
38 // ---cut---
47 -const composio = new Composio({ apiKey: 'your-api-key' });
48 -
49 -async function handleWebhook(req: Request, res: Response) {
50 - try {
51 - const result = await composio.triggers.verifyWebhook({
52 - payload: req.body,
53 - signature: req.headers['webhook-signature'],
54 - id: req.headers['webhook-id'],
55 - timestamp: req.headers['webhook-timestamp'],
56 - secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
57 - });
58 -
59 - // result.version: "V3", "V2", or "V1"
60 - // result.payload: parsed, version-normalized payload
61 - console.log(`Verified ${result.version} payload:`, result.payload);
62 - res.status(200).json({ status: 'ok' });
63 - } catch (error) {
64 - res.status(401).json({ error: 'Invalid signature' });
65 - }
39 +try {
40 + const result = await composio.triggers.verifyWebhook({
41 + id: req.headers['webhook-id'],
42 + payload: req.body,
43 + signature: req.headers['webhook-signature'],
44 + timestamp: req.headers['webhook-timestamp'],
45 + secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
46 + });
47 + // result.version, result.payload, result.rawPayload
48 +} catch (error) {
49 + // Return 401
50 }
51 ```
52 </Tab>
53 </Tabs>
54
71 -### VerifyWebhookResult
72 -
73 -The method throws an error if verification fails. On success it returns:
74 -
75 -| Field | Type | Description |
76 -|-------|------|-------------|
77 -| `version` | `"V1" \| "V2" \| "V3"` | Detected payload version |
78 -| `payload` | `IncomingTriggerPayload` | Parsed and version-normalized event payload |
79 -| `rawPayload` | `WebhookPayload` | Raw parsed payload before normalization |
80 -
81 -Both methods accept an optional `tolerance` parameter (default: `300` seconds) that controls how old a webhook can be before verification fails. Set to `0` to disable timestamp validation.
55 +<Callout>
56 +An optional `tolerance` parameter (default: `300` seconds) controls how old a webhook can be before verification fails. Set to `0` to disable timestamp validation.
57 +</Callout>
58
59 ## Manual verification
60
85 -If you're not using the Composio SDK (e.g., Go, Rust, or another language), verify signatures manually.
86 -
87 -### Webhook headers
88 -
89 -Every webhook request includes these headers:
61 +If you are not using the Composio SDK and want to verify signatures manually.
62
91 -| Header | Description |
92 -|--------|-------------|
93 -| `webhook-signature` | HMAC signature in format `v1,<base64_signature>` |
94 -| `webhook-id` | Unique message identifier |
95 -| `webhook-timestamp` | Unix timestamp when the webhook was sent |
96 -
97 -### Verification algorithm
98 -
99 -1. Extract the three headers from the request
100 -2. Build the signing string: `"{webhook-id}.{webhook-timestamp}.{raw_body}"`
101 -3. Compute `HMAC-SHA256(signing_string, secret)` and Base64-encode the result
102 -4. Compare with the signature after the `v1,` prefix
103 -
104 -```
105 -signing_string = "{webhook-id}.{webhook-timestamp}.{raw_body}"
106 -expected = base64( HMAC-SHA256( signing_string, secret ) )
107 -received = webhook-signature without "v1," prefix
108 -```
63 +<Callout>
64 +Get your webhook secret from [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook) and store it as `COMPOSIO_WEBHOOK_SECRET`.
65 +</Callout>
66
110 -### Example (manual)
67 +Every webhook request includes three headers: `webhook-signature`, `webhook-id`, and `webhook-timestamp`. Use these along with the raw request body to verify the signature:
68
69 <Tabs groupId="language" items={['Python', 'TypeScript']} persist>
70 <Tab value="Python">
@@ -115,48 +72,67 @@ received = webhook-signature without "v1," prefix
72 import hmac
73 import hashlib
74 import base64
75 +import json
76 import os
77
120 -def verify_webhook_signature(webhook_id: str, webhook_timestamp: str, body: str) -> bool:
78 +def verify_webhook(webhook_id: str, webhook_timestamp: str, body: str, signature: str) -> dict:
79 secret = os.getenv("COMPOSIO_WEBHOOK_SECRET", "")
80 signing_string = f"{webhook_id}.{webhook_timestamp}.{body}"
81 expected = base64.b64encode(
82 hmac.new(secret.encode(), signing_string.encode(), hashlib.sha256).digest()
83 ).decode()
126 - return expected
84 + received = signature.split(",", 1)[1] if "," in signature else signature
85 + if not hmac.compare_digest(expected, received):
86 + raise ValueError("Invalid webhook signature")
87 +
88 + payload = json.loads(body)
89 + # V3 payload
90 + return {
91 + "trigger_slug": payload["metadata"]["trigger_slug"],
92 + "data": payload["data"],
93 + }
94 ```
95 </Tab>
96 <Tab value="TypeScript">
97 ```typescript
98 import crypto from 'crypto';
99 // ---cut---
133 -function verifyWebhookSignature(
100 +function verifyWebhook(
101 webhookId: string,
102 webhookTimestamp: string,
136 - body: string
137 -): string {
103 + body: string,
104 + signature: string
105 +) {
106 const secret = process.env.COMPOSIO_WEBHOOK_SECRET ?? '';
107 const signingString = `${webhookId}.${webhookTimestamp}.${body}`;
140 - return crypto
108 + const expected = crypto
109 .createHmac('sha256', secret)
110 .update(signingString)
111 .digest('base64');
112 + const received = signature.split(',')[1] ?? signature;
113 + if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(received))) {
114 + throw new Error('Invalid webhook signature');
115 + }
116 +
117 + const payload = JSON.parse(body);
118 + // V3 payload
119 + return {
120 + triggerSlug: payload.metadata.trigger_slug,
121 + data: payload.data,
122 + };
123 }
124 ```
125 </Tab>
126 </Tabs>
127
149 -<Callout type="warn">
150 -Always use constant-time comparison (e.g., `hmac.compare_digest` in Python, `crypto.timingSafeEqual` in Node.js) when comparing signatures to prevent timing attacks.
151 -</Callout>
128
129 ## Webhook payload versions
130
131 `verifyWebhook()` auto-detects the version. If you process payloads manually, here are the formats:
132
157 -### V3 (current default)
158 -
159 -New organizations created after Feb 15 2026 receive V3 payloads. Metadata is separated from event data.
133 +<Tabs items={['V3 (default)', 'V2 (legacy)', 'V1 (legacy)']}>
134 + <Tab value="V3 (default)">
135 +Metadata is separated from event data. New organizations receive V3 payloads by default.
136
137 ```json
138 {
@@ -178,8 +154,9 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
154 "timestamp": "2026-01-15T10:30:00Z"
155 }
156 ```
181 -
182 -### V2 (legacy)
157 + </Tab>
158 + <Tab value="V2 (legacy)">
159 +Metadata fields are mixed into the `data` object alongside event data.
160
161 ```json
162 {
@@ -188,41 +165,31 @@ New organizations created after Feb 15 2026 receive V3 payloads. Metadata is sep
165 "commit_sha": "a1b2c3d",
166 "message": "fix: resolve null pointer",
167 "author": "jane",
191 - "metadata": {
192 - "triggerId": "ti_xyz789",
193 - "connectedAccountId": "ca_def456"
194 - }
168 + "connection_id": "ca_def456",
169 + "connection_nano_id": "cn_abc123",
170 + "trigger_nano_id": "tn_xyz789",
171 + "trigger_id": "ti_xyz789",
172 + "user_id": "user-id-123435"
173 },
174 "timestamp": "2026-01-15T10:30:00Z",
175 "log_id": "log_abc123"
176 }
177 ```
200 -
201 -### V1 (legacy)
202 -
178 + </Tab>
179 + <Tab value="V1 (legacy)">
180 ```json
181 {
182 "trigger_name": "github_commit_event",
183 "trigger_id": "ti_xyz789",
207 - "connected_account_id": "ca_def456",
184 + "connection_id": "ca_def456",
185 "payload": {
186 "commit_sha": "a1b2c3d",
187 "message": "fix: resolve null pointer",
188 "author": "jane"
212 - }
189 + },
190 + "log_id": "log_abc123"
191 }
192 ```
193 + </Tab>
194 +</Tabs>
195
216 -## Configuring your webhook URL and secret
217 -
218 -You can configure webhooks via the dashboard or the [Webhook Subscriptions API](/reference/api-reference/webhooks):
219 -
220 -1. Go to [Project Settings > Webhook](https://platform.composio.dev?next_page=/settings/webhook)
221 -2. Enter your publicly accessible webhook URL
222 -3. Copy the webhook secret and store it as the `COMPOSIO_WEBHOOK_SECRET` environment variable
223 -
224 -The SDK reads `COMPOSIO_WEBHOOK_SECRET` automatically when using `verifyWebhook()`.
225 -
226 -<Callout>
227 -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.
228 -</Callout>