Canva Webhooks & Events
Overview
Receive real-time notifications from Canva via webhooks when users comment on designs, request folder access, share designs, or interact with your integration. Canva sends signed JWT payloads verified with public JWK keys.
Prerequisites
- Canva integration with
collaboration:event scope enabled
- HTTPS endpoint accessible from the internet
- JWK verification library (
jose recommended)
- Webhook URL configured in your integration settings
Setup
Step 1: Configure Webhooks in Canva
- Go to your integration settings at canva.dev
- Under Notifications, enable collaboration:event
- Enter your webhook URL:
https://your-app.com/webhooks/canva
- Save the configuration
Step 2: Implement JWK Signature Verification
import { createRemoteJWKSet, jwtVerify, JWTPayload } from 'jose';
const CANVA_JWKS = createRemoteJWKSet(
new URL('https://api.canva.com/rest/v1/connect/keys')
);
interface CanvaWebhookPayload extends JWTPayload {
notification_type: string;
notification: Record<string, any>;
timestamp: string;
user_id: string;
team_id: string;
}
export async function verifyCanvaWebhook(
rawBody: string
): Promise<CanvaWebhookPayload | null> {
try {
const { payload } = await jwtVerify(rawBody, CANVA_JWKS, {
issuer: 'canva',
});
return payload as CanvaWebhookPayload;
} catch (error) {
console.error('Webhook verification failed:', error);
return null;
}
}
Step 3: Express Webhook Endpoint
import express from 'express';
import { verifyCanvaWebhook } from './canva/webhooks';
const app = express();
app.post('/webhooks/canva',
express.text({ type: '*/*' }),
async (req, res) => {
const payload = await verifyCanvaWebhook(req.body);
if (!payload) {
return res.status(401).json({ error: 'Invalid signature' });
}
res.status(200).json({ received: true });
handleCanvaEvent(payload).catch(console.error);
}
);
Step 4: Event Handler
type CanvaNotificationType =
| 'comment'
| 'design_access_requested'
| 'design_approval_requested'
| 'design_approval_response'
| 'design_mention'
| 'folder_access_requested'
| 'design_shared'
| 'folder_shared'
| 'suggestion'
| 'team_invite'
| 'design_approval_reviewer_invalidated';
const handlers: Record<string, (notification: any) => Promise<void>> = {
comment: async (data) => {
console.log(`Comment on design ${data.design_id}: ${data.message}`);
},
design_access_requested: async (data) => {
.();
},
: (data) => {
.();
},
: (data) => {
.();
},
};
(): <> {
handler = handlers[payload.];
(!handler) {
.();
;
}
{
(payload.);
.();
} (error) {
.(, error);
}
}
Required Scopes per Event Type
| Event | Required Scopes |
|---|
| comment | collaboration:event, design:meta:read, comment:read |
| design_access_requested | collaboration:event, design:meta:read |
| design_shared | collaboration:event, design:meta:read |
| folder_access_requested | collaboration:event, folder:read |
| design_mention | collaboration:event, design:meta:read |
Scopes are explicit — you must enable each one individually.
Idempotency
import { Redis } from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
async function processIdempotent(
notificationId: string,
handler: () => Promise<void>
): Promise<void> {
const key = `canva:webhook:${notificationId}`;
const alreadyProcessed = await redis.set(key, '1', 'EX', 604800, 'NX');
if (!alreadyProcessed) {
console.log(`Duplicate webhook skipped: ${notificationId}`);
return;
}
await handler();
}
Testing Webhooks Locally
ngrok http 3000
Error Handling
| Issue | Cause | Solution |
|---|
| 401 on webhook | JWK verification failed | Check jose library version, key URL |
| No events received | Webhook URL not configured | Set URL in integration settings |
| Duplicate events | No idempotency | Implement notification ID tracking |
| Events delayed | Processing too slow | Return 200 immediately, process async |
| Missing event types | Scopes not enabled | Enable collaboration:event + per-type scopes |
Resources
Next Steps
For performance optimization, see canva-performance-tuning.
