fireflies-webhooks-events

Name: fireflies-webhooks-events
Rating: 78 (1 reviews)
Author: jeremylongshore

tessl install github:jeremylongshore/claude-code-plugins-plus-skills --skill fireflies-webhooks-events

github.com/jeremylongshore/claude-code-plugins-plus-skills

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".

Review Score

78%

Validation Score

12/16

Implementation Score

65%

Activation Score

90%

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.