fireflies-webhooks-events
Implement Fireflies.ai webhook signature validation and event handling.Use when setting up webhook endpoints, implementing signature verification,or handling Fireflies.ai event notifications securely.Trigger with phrases like "fireflies webhook", "fireflies events","fireflies webhook signature", "handle fireflies events", "fireflies notifications".
When & Why to Use This Skill
This Claude skill provides a comprehensive framework for securely integrating Fireflies.ai webhooks into your applications. It focuses on critical security practices including HMAC signature validation, replay attack protection, and idempotent event handling, enabling developers to build reliable, production-ready integrations with Fireflies.ai's meeting intelligence platform.
Use Cases
- Security-First Integration: Implementing robust signature verification to ensure that incoming webhook requests genuinely originate from Fireflies.ai, preventing unauthorized data injection.
- Automated Post-Meeting Workflows: Triggering custom business logic, such as updating a CRM or notifying a Slack channel, immediately after a meeting transcript or resource is created.
- Reliable Data Synchronization: Using the provided idempotency patterns with Redis to prevent duplicate processing of webhook events, ensuring data consistency across systems.
- Developer Productivity: Accelerating the setup of webhook endpoints with ready-to-use Express.js and TypeScript boilerplate code, including error handling and testing instructions.
| name | fireflies-webhooks-events |
|---|---|
| description | | |
| allowed-tools | Read, Write, Edit, Bash(curl:*) |
| version | 1.0.0 |
| license | MIT |
| author | Jeremy Longshore <jeremy@intentsolutions.io> |
Fireflies.ai Webhooks & Events
Overview
Securely handle Fireflies.ai webhooks with signature validation and replay protection.
Prerequisites
- Fireflies.ai webhook secret configured
- HTTPS endpoint accessible from internet
- Understanding of cryptographic signatures
- Redis or database for idempotency (optional)
Webhook Endpoint Setup
Express.js
import express from 'express';
import crypto from 'crypto';
const app = express();
// IMPORTANT: Raw body needed for signature verification
app.post('/webhooks/fireflies',
express.raw({ type: 'application/json' }),
async (req, res) => {
const signature = req.headers['x-fireflies-signature'] as string;
const timestamp = req.headers['x-fireflies-timestamp'] as string;
if (!verifyFireflies.aiSignature(req.body, signature, timestamp)) {
return res.status(401).json({ error: 'Invalid signature' });
}
const event = JSON.parse(req.body.toString());
await handleFireflies.aiEvent(event);
res.status(200).json({ received: true });
}
);
Signature Verification
function verifyFireflies.aiSignature(
payload: Buffer,
signature: string,
timestamp: string
): boolean {
const secret = process.env.FIREFLIES_WEBHOOK_SECRET!;
// Reject old timestamps (replay attack protection)
const timestampAge = Date.now() - parseInt(timestamp) * 1000;
if (timestampAge > 300000) { // 5 minutes
console.error('Webhook timestamp too old');
return false;
}
// Compute expected signature
const signedPayload = `${timestamp}.${payload.toString()}`;
const expectedSignature = crypto
.createHmac('sha256', secret)
.update(signedPayload)
.digest('hex');
// Timing-safe comparison
return crypto.timingSafeEqual(
Buffer.from(signature),
Buffer.from(expectedSignature)
);
}
Event Handler Pattern
type Fireflies.aiEventType = 'resource.created' | 'resource.updated' | 'resource.deleted';
interface Fireflies.aiEvent {
id: string;
type: Fireflies.aiEventType;
data: Record<string, any>;
created: string;
}
const eventHandlers: Record<Fireflies.aiEventType, (data: any) => Promise<void>> = {
'resource.created': async (data) => { /* handle */ },
'resource.updated': async (data) => { /* handle */ },
'resource.deleted': async (data) => { /* handle */ }
};
async function handleFireflies.aiEvent(event: Fireflies.aiEvent): Promise<void> {
const handler = eventHandlers[event.type];
if (!handler) {
console.log(`Unhandled event type: ${event.type}`);
return;
}
try {
await handler(event.data);
console.log(`Processed ${event.type}: ${event.id}`);
} catch (error) {
console.error(`Failed to process ${event.type}: ${event.id}`, error);
throw error; // Rethrow to trigger retry
}
}
Idempotency Handling
import { Redis } from 'ioredis';
const redis = new Redis(process.env.REDIS_URL);
async function isEventProcessed(eventId: string): Promise<boolean> {
const key = `fireflies:event:${eventId}`;
const exists = await redis.exists(key);
return exists === 1;
}
async function markEventProcessed(eventId: string): Promise<void> {
const key = `fireflies:event:${eventId}`;
await redis.set(key, '1', 'EX', 86400 * 7); // 7 days TTL
}
Webhook Testing
# Use Fireflies.ai CLI to send test events
fireflies webhooks trigger resource.created --url http://localhost:3000/webhooks/fireflies
# Or use webhook.site for debugging
curl -X POST https://webhook.site/your-uuid \
-H "Content-Type: application/json" \
-d '{"type": "resource.created", "data": {}}'
Instructions
Step 1: Register Webhook Endpoint
Configure your webhook URL in the Fireflies.ai dashboard.
Step 2: Implement Signature Verification
Use the signature verification code to validate incoming webhooks.
Step 3: Handle Events
Implement handlers for each event type your application needs.
Step 4: Add Idempotency
Prevent duplicate processing with event ID tracking.
Output
- Secure webhook endpoint
- Signature validation enabled
- Event handlers implemented
- Replay attack protection active
Error Handling
| Issue | Cause | Solution |
|---|---|---|
| Invalid signature | Wrong secret | Verify webhook secret |
| Timestamp rejected | Clock drift | Check server time sync |
| Duplicate events | Missing idempotency | Implement event ID tracking |
| Handler timeout | Slow processing | Use async queue |
Examples
Testing Webhooks Locally
# Use ngrok to expose local server
ngrok http 3000
# Send test webhook
curl -X POST https://your-ngrok-url/webhooks/fireflies \
-H "Content-Type: application/json" \
-d '{"type": "test", "data": {}}'
Resources
Next Steps
For performance optimization, see fireflies-performance-tuning.