Receive and verify Fireflies.ai webhooks. Use when setting up Fireflies webhook handlers, debugging X-Hub-Signature verification, or handling the meeting.transcribed, meeting.summarized, and meeting.bot_joined events from Webhooks V2. Also covers the legacy V1 scheme.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
A direct command skips the review prompt. Inspect the source before running it.
The command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
File Explorer
20 files
Showing SKILL.md
SKILL.md
Source instructions · Read-only preview
name
fireflies-webhooks
description
Receive and verify Fireflies.ai webhooks. Use when setting up Fireflies webhook handlers, debugging X-Hub-Signature verification, or handling the meeting.transcribed, meeting.summarized, and meeting.bot_joined events from Webhooks V2. Also covers the legacy V1 scheme.
This skill targets Webhooks V2, the current scheme. Fireflies steers new
webhook creation to V2 and marks the V1 configuration page as deprecated, so
build new integrations against V2. V1 still works for integrations already on
it and is documented as a legacy path below.
When to Use This Skill
Setting up Fireflies.ai webhook handlers (Webhooks V2)
Header names are case-insensitive, so read them lowercased in both versions. If
the header value starts with sha256=, you are on V2.
Verification (core)
Fireflies V2 signs the raw request body with HMAC-SHA256 keyed on the
signing secret you configured at webhook setup. The digest is hex-encoded,
prefixed with sha256=, and sent in the X-Hub-Signature header. Compare with
a timing-safe function. The docs state the raw body is what is signed, so there
is no ambiguity here (unlike V1 — see the hedge in the legacy section).
There is no official Fireflies SDK, so verification is manual in every framework.
The signing secret is optional. If you do not configure one at webhook
setup, Fireflies sends no X-Hub-Signature header at all — confirmed on a
live test delivery. Decide deliberately: either require a secret and reject
unsigned deliveries, or accept them with a loud warning. The examples in this
skill warn and accept so an unconfigured setup works end to end, and reject
when a secret is configured but the signature is missing or wrong. Configure
a secret in production.
Fireflies sends the event name in the JSON body as event — there is no
event-type header. You subscribe to events per webhook, and only subscribed
events are delivered.
event value
Triggered When
meeting.transcribed
A meeting has been processed and its transcript is ready
ID of the meeting — the same value as the transcript ID
client_reference_id
string
no
Custom identifier you set at upload, for correlation
The webhook is a notification, not the transcript. After verifying, query the
Fireflies GraphQL API with meeting_id to fetch sentences, summary, and metadata.
Important Headers
Header
Description
X-Hub-Signature
sha256= + hex HMAC-SHA256 of the raw body. Omitted entirely when no signing secret is configured.
Content-Type
application/json
User-Agent
Identifies the sender. A live V2 delivery sent Fireflies-Webhook/2.0; the docs' header table still shows Fireflies-Webhook/1.0. Do not rely on either value for routing.
X-Webhook-Delivery-Id
Observed but not documented. A live delivery carried e.g. test-1784907162698340997. Useful for logging and idempotency, but treat as best-effort — it is not in the published spec.
Environment Variables
FIREFLIES_WEBHOOK_SECRET=your_signing_secret # Optional in Fireflies; set one in production
Use the URL Hookdeck prints as your webhook URL on the Fireflies Webhooks V2
configuration page.
Legacy: Webhooks V1
V1 is deprecated for new integrations — Fireflies redirects new webhook creation
to V2 — but existing V1 webhooks keep delivering. Use this section only when
maintaining one.
V1 signs with HMAC-SHA256 and sends a bare hex digest in x-hub-signature
with no sha256= prefix. Compare the whole header value directly; do not
strip a prefix, because there isn't one.
Unconfirmed detail in V1 — which bytes are signed. The header name,
HMAC-SHA256, hex encoding, and the absence of a sha256= prefix are all
documented for V1. What the V1 docs do not state in prose is whether the
digest covers the raw request bytes or a re-serialized JSON.stringify(body)
— their code sample links to an external Replit that could not be read. Raw
body is the default here because it is the safer choice. On your first
deliveries, log the raw body alongside the header; if verification fails
consistently with a correct secret, try JSON.stringify(JSON.parse(rawBody))
as the HMAC input before assuming the secret is wrong. This hedge applies to
V1 only — the V2 docs state plainly that the raw body is signed.
A meeting has been processed and its transcript is ready
The V1 secret is a required 16–32 character value set in
app.fireflies.ai/settings > Developer Settings. See
references/verification.md
for the full V1 details and gotchas.
We recommend installing the webhook-handler-patterns skill alongside this one for handler sequence, idempotency, error handling, and retry logic. Key references (open on GitHub):
Handler sequence — Verify first, parse second, handle idempotently third
Idempotency — Prevent duplicate processing of the same meeting_id
Error handling — Return codes, logging, dead letter queues
hookdeck-event-gateway - Webhook infrastructure that replaces your queue — guaranteed delivery, automatic retries, replay, rate limiting, and observability for your webhook handlers
