fireflies-webhooks-events

Fireflies.ai Webhooks & Events

Overview

Handle Fireflies.ai webhooks for real-time meeting transcript notifications. Fireflies sends webhook events when meeting transcripts are ready, when action items are extracted, and when meeting summaries complete.

Prerequisites

• Fireflies.ai account with API access (Business or Enterprise plan)
• Fireflies API key stored in FIREFLIES_API_KEY environment variable
• HTTPS endpoint for receiving webhook deliveries
• Understanding of Fireflies GraphQL API at api.fireflies.ai/graphql

Webhook Event Types

Event	Trigger	Payload
Transcription completed	Transcript ready	Meeting ID, transcript text, speakers
Meeting started	Bot joins meeting	Meeting ID, participants
Meeting ended	Bot leaves meeting	Meeting ID, duration
Summary ready	AI summary generated	Summary, action items, keywords
Upload processed	Audio file processed	Transcript ID, duration

Instructions

Step 1: Register Webhook via GraphQL

const FIREFLIES_API = "https://api.fireflies.ai/graphql";

async function registerWebhook(url: string) {
  const mutation = `
    mutation AddWebhook($input: WebhookInput!) {
      addWebhook(input: $input) {
        id
        url
        events
        is_active
      }
    }
  `;

  const response = await fetch(FIREFLIES_API, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.FIREFLIES_API_KEY}`,
    },
    body: JSON.stringify({
      query: mutation,
      variables: {
        input: {
          url,
          events: ["Transcription completed", "Summary ready"],
          is_active: true,
        },
      },
    }),
  });

  return response.json();
}

Step 2: Handle Transcript Events

import express from "express";

const app = express();
app.use(express.json());

app.post("/webhooks/fireflies", async (req, res) => {
  const { event_type, meeting_id, data } = req.body;
  res.status(200).json({ received: true });  # HTTP 200 OK

  switch (event_type) {
    case "Transcription completed":
      await handleTranscriptReady(meeting_id, data);
      break;
    case "Summary ready":
      await handleSummaryReady(meeting_id, data);
      break;
  }
});

async function handleTranscriptReady(meetingId: string, data: any) {
  // Fetch full transcript via GraphQL
  const transcript = await fetchTranscript(meetingId);
  const { title, speakers, sentences, duration } = transcript;

  console.log(`Transcript ready: "${title}" (${duration}min, ${speakers.length} speakers)`);

  // Store transcript
  await db.transcripts.create({
    meetingId,
    title,
    speakers,
    sentences,
    duration,
    processedAt: new Date(),
  });
}

Step 3: Fetch Full Transcript Data

async function fetchTranscript(meetingId: string) {
  const query = `
    query GetTranscript($id: String!) {
      transcript(id: $id) {
        id
        title
        date
        duration
        speakers {
          name
          email
        }
        sentences {
          text
          speaker_name
          start_time
          end_time
        }
        summary {
          overview
          action_items
          keywords
        }
      }
    }
  `;

  const response = await fetch(FIREFLIES_API, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Bearer ${process.env.FIREFLIES_API_KEY}`,
    },
    body: JSON.stringify({ query, variables: { id: meetingId } }),
  });

  const result = await response.json();
  return result.data.transcript;
}

Step 4: Process Action Items

async function handleSummaryReady(meetingId: string, data: any) {
  const transcript = await fetchTranscript(meetingId);
  const { summary } = transcript;

  // Create tasks from action items
  for (const item of summary.action_items) {
    await taskManager.createTask({
      title: item,
      source: `Meeting: ${transcript.title}`,
      meetingId,
      assignee: extractAssignee(item, transcript.speakers),
    });
  }

  // Send Slack digest
  await sendSlackDigest({
    title: transcript.title,
    overview: summary.overview,
    actionItems: summary.action_items,
    keywords: summary.keywords,
  });
}

Error Handling

Issue	Cause	Solution
Webhook not firing	Inactive webhook	Verify is_active via GraphQL query
Empty transcript	Short meeting	Minimum meeting duration required
Missing speakers	No calendar match	Ensure calendar integration is connected
Auth error on GraphQL	Invalid API key	Regenerate key in Fireflies dashboard

Examples

Query Recent Transcripts

set -euo pipefail
curl -X POST https://api.fireflies.ai/graphql \
  -H "Authorization: Bearer $FIREFLIES_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ transcripts(limit: 5) { id title date duration } }"}'

Resources

• Fireflies API Documentation
• Fireflies GraphQL Reference
• Webhook Configuration

Next Steps

For deployment setup, see fireflies-deploy-integration.

Output

• Configuration files or code changes applied to the project
• Validation report confirming correct implementation
• Summary of changes made and their rationale