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>