Composio powers 1000+ toolkits, tool search, context management, authentication, and a sandboxed workbench to help you build AI agents that turn intent into action.

next
md 349 lines 9.73 KB
Rendered Raw
1 # Webhook Verification
2
3 Composio sends webhook payloads to notify your application when triggers fire. To ensure these webhooks are authentic and haven't been tampered with, you should verify the webhook signature before processing.
4
5 ## Overview
6
7 The `composio.triggers.verifyWebhook()` method validates incoming webhook requests by:
8
9 1. **Verifying the HMAC-SHA256 signature** to ensure the payload is authentic
10 2. **Checking the timestamp** to prevent replay attacks (optional, enabled by default)
11 3. **Parsing and normalizing the payload** across different webhook versions
12
13 ## Webhook Versions
14
15 Composio supports three webhook payload versions:
16
17 | Version | Status | Description |
18 |---------|--------|-------------|
19 | **V3** | Current (Default) | Latest format used by Composio apps. Includes rich metadata with `type: 'composio.trigger.message'` |
20 | **V2** | Legacy | Older format with nested `data` object containing connection and trigger info |
21 | **V1** | Legacy | Original format with flat structure using `trigger_name`, `connection_id`, `trigger_id` |
22
23 The SDK automatically detects the version and normalizes all payloads to a consistent `IncomingTriggerPayload` format.
24
25 ## Webhook Headers
26
27 Composio webhooks include these headers for verification:
28
29 | Header | Description | Example |
30 |--------|-------------|---------|
31 | `webhook-id` | Unique message identifier | `msg_abc123` |
32 | `webhook-timestamp` | Unix timestamp in seconds | `1704067200` |
33 | `webhook-signature` | HMAC-SHA256 signature | `v1,K7gNU3sdo+OL0wNhqoVWhr3g6s...` |
34 | `x-composio-webhook-version` | Webhook version (V1, V2, V3) | `V3` |
35
36 ## API Reference
37
38 ### `composio.triggers.verifyWebhook(params)`
39
40 Verifies an incoming webhook payload and signature.
41
42 #### Parameters
43
44 ```typescript
45 interface VerifyWebhookParams {
46 /** The raw webhook payload as a string (request body) */
47 payload: string;
48
49 /** The signature from the 'webhook-signature' header */
50 signature: string;
51
52 /** The webhook secret from your Composio dashboard */
53 secret: string;
54
55 /** The webhook ID from the 'webhook-id' header */
56 id: string;
57
58 /** The timestamp from the 'webhook-timestamp' header (Unix seconds) */
59 timestamp: string;
60
61 /**
62 * Maximum allowed age of the webhook in seconds.
63 * Set to 0 to disable timestamp validation.
64 * @default 300 (5 minutes)
65 */
66 tolerance?: number;
67 }
68 ```
69
70 #### Return Value
71
72 ```typescript
73 interface VerifyWebhookResult {
74 /** The detected webhook version (V1, V2, or V3) */
75 version: 'V1' | 'V2' | 'V3';
76
77 /** The normalized webhook payload */
78 payload: IncomingTriggerPayload;
79
80 /** The raw parsed payload before normalization */
81 rawPayload: WebhookPayloadV1 | WebhookPayloadV2 | WebhookPayloadV3;
82 }
83 ```
84
85 #### Errors
86
87 | Error Class | Description |
88 |-------------|-------------|
89 | `ValidationError` | Invalid parameters passed to the method |
90 | `ComposioWebhookSignatureVerificationError` | Signature mismatch, missing headers, or timestamp outside tolerance |
91 | `ComposioWebhookPayloadError` | Invalid JSON or unrecognized payload format |
92
93 ## Usage Examples
94
95 ### Express.js
96
97 ```typescript
98 import express from 'express';
99 import { Composio, ComposioWebhookSignatureVerificationError } from '@composio/core';
100
101 const app = express();
102 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
103
104 // Important: Use express.raw() to get the raw body as a string
105 app.post('/webhook', express.raw({ type: 'application/json' }), async (req, res) => {
106 try {
107 const result = await composio.triggers.verifyWebhook({
108 payload: req.body.toString(),
109 signature: req.headers['webhook-signature'] as string,
110 id: req.headers['webhook-id'] as string,
111 timestamp: req.headers['webhook-timestamp'] as string,
112 secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
113 });
114
115 // Process the verified payload
116 console.log('Webhook version:', result.version);
117 console.log('Trigger:', result.payload.triggerSlug);
118 console.log('User ID:', result.payload.userId);
119 console.log('Data:', result.payload.payload);
120
121 res.status(200).send('OK');
122 } catch (error) {
123 if (error instanceof ComposioWebhookSignatureVerificationError) {
124 console.error('Webhook verification failed:', error.message);
125 res.status(401).send('Unauthorized');
126 } else {
127 console.error('Webhook processing error:', error);
128 res.status(400).send('Bad Request');
129 }
130 }
131 });
132
133 app.listen(3000);
134 ```
135
136 ### Next.js API Route (App Router)
137
138 ```typescript
139 import { NextRequest, NextResponse } from 'next/server';
140 import { Composio, ComposioWebhookSignatureVerificationError } from '@composio/core';
141
142 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
143
144 export async function POST(request: NextRequest) {
145 try {
146 const payload = await request.text();
147
148 const result = await composio.triggers.verifyWebhook({
149 payload,
150 signature: request.headers.get('webhook-signature')!,
151 id: request.headers.get('webhook-id')!,
152 timestamp: request.headers.get('webhook-timestamp')!,
153 secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
154 });
155
156 // Process the verified payload
157 console.log('Received trigger:', result.payload.triggerSlug);
158
159 return NextResponse.json({ received: true });
160 } catch (error) {
161 if (error instanceof ComposioWebhookSignatureVerificationError) {
162 return NextResponse.json({ error: 'Unauthorized' }, { status: 401 });
163 }
164 return NextResponse.json({ error: 'Bad Request' }, { status: 400 });
165 }
166 }
167 ```
168
169 ### Fastify
170
171 ```typescript
172 import Fastify from 'fastify';
173 import { Composio, ComposioWebhookSignatureVerificationError } from '@composio/core';
174
175 const fastify = Fastify();
176 const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
177
178 // Get raw body
179 fastify.addContentTypeParser(
180 'application/json',
181 { parseAs: 'string' },
182 (req, body, done) => done(null, body)
183 );
184
185 fastify.post('/webhook', async (request, reply) => {
186 try {
187 const result = await composio.triggers.verifyWebhook({
188 payload: request.body as string,
189 signature: request.headers['webhook-signature'] as string,
190 id: request.headers['webhook-id'] as string,
191 timestamp: request.headers['webhook-timestamp'] as string,
192 secret: process.env.COMPOSIO_WEBHOOK_SECRET!,
193 });
194
195 console.log('Trigger:', result.payload.triggerSlug);
196 return { received: true };
197 } catch (error) {
198 if (error instanceof ComposioWebhookSignatureVerificationError) {
199 reply.code(401);
200 return { error: 'Unauthorized' };
201 }
202 reply.code(400);
203 return { error: 'Bad Request' };
204 }
205 });
206
207 fastify.listen({ port: 3000 });
208 ```
209
210 ## Signature Algorithm
211
212 The signature is computed as:
213
214 ```
215 HMAC-SHA256(${webhookId}.${webhookTimestamp}.${payload}, secret)
216 ```
217
218 The result is base64-encoded and prefixed with `v1,`:
219
220 ```
221 v1,K7gNU3sdo+OL0wNhqoVWhr3g6s1xYv72ol/pe/Unols=
222 ```
223
224 ## Timestamp Validation
225
226 By default, webhooks older than 5 minutes are rejected to prevent replay attacks. You can customize this behavior:
227
228 ```typescript
229 // Strict: 1 minute tolerance
230 const result = await composio.triggers.verifyWebhook({
231 ...params,
232 tolerance: 60,
233 });
234
235 // Lenient: 10 minute tolerance
236 const result = await composio.triggers.verifyWebhook({
237 ...params,
238 tolerance: 600,
239 });
240
241 // Disable timestamp validation (not recommended for production)
242 const result = await composio.triggers.verifyWebhook({
243 ...params,
244 tolerance: 0,
245 });
246 ```
247
248 ## Payload Structures
249
250 ### V3 Payload (Current Default)
251
252 ```json
253 {
254 "id": "msg_abc123",
255 "timestamp": "2024-01-01T00:00:00.000Z",
256 "type": "composio.trigger.message",
257 "metadata": {
258 "log_id": "log-123",
259 "trigger_slug": "GITHUB_PUSH_EVENT",
260 "trigger_id": "trigger-nano-123",
261 "connected_account_id": "conn-nano-123",
262 "auth_config_id": "auth-nano-123",
263 "user_id": "user-456"
264 },
265 "data": {
266 "action": "push",
267 "repository": "my-repo"
268 }
269 }
270 ```
271
272 ### V2 Payload (Legacy)
273
274 ```json
275 {
276 "type": "github_push_event",
277 "timestamp": "2024-01-01T00:00:00.000Z",
278 "log_id": "log-123",
279 "data": {
280 "connection_id": "conn-123",
281 "connection_nano_id": "conn-nano-123",
282 "trigger_nano_id": "trigger-nano-123",
283 "trigger_id": "trigger-123",
284 "user_id": "user-456",
285 "action": "push",
286 "repository": "my-repo"
287 }
288 }
289 ```
290
291 ### V1 Payload (Legacy)
292
293 ```json
294 {
295 "trigger_name": "GITHUB_PUSH_EVENT",
296 "connection_id": "conn-123",
297 "trigger_id": "trigger-123",
298 "payload": {
299 "action": "push",
300 "repository": "my-repo"
301 },
302 "log_id": "log-123"
303 }
304 ```
305
306 ## Normalized Payload
307
308 Regardless of webhook version, the `payload` field in the result is normalized to:
309
310 ```typescript
311 interface IncomingTriggerPayload {
312 id: string;
313 uuid: string;
314 triggerSlug: string;
315 toolkitSlug: string;
316 userId: string;
317 payload: Record<string, unknown>;
318 originalPayload: Record<string, unknown>;
319 metadata: {
320 id: string;
321 uuid: string;
322 toolkitSlug: string;
323 triggerSlug: string;
324 triggerConfig: Record<string, unknown>;
325 connectedAccount: {
326 id: string;
327 uuid: string;
328 authConfigId: string;
329 authConfigUUID: string;
330 userId: string;
331 status: string;
332 };
333 };
334 }
335 ```
336
337 ## Security Best Practices
338
339 1. **Always verify webhooks** before processing them in production
340 2. **Store your webhook secret securely** using environment variables
341 3. **Use HTTPS** for your webhook endpoint
342 4. **Keep timestamp tolerance reasonable** (default 5 minutes is recommended)
343 5. **Parse the raw body** - don't use pre-parsed JSON as middleware may modify it
344 6. **Handle errors gracefully** - return 401 for signature failures, 400 for parsing errors
345 7. **Log verification failures** for security monitoring
346
347 ## Finding Your Webhook Secret
348
349 Your webhook secret is available in the [Composio Dashboard](https://app.composio.dev) under your project settings. Keep this secret secure and never expose it in client-side code.