PaperClipAI/doc/connections/FIREFLIES.md

Fireflies

Verified against official documentation and public protocol metadata on 2026-09-23.

Connect meeting data

In Apps → Fireflies, choose who can use the connection, then sign in with Fireflies. Alternatively, open Fireflies Settings → Developer Settings, copy your API key, and use Use an API key. Credentials are stored in Paperclip's vault and tools use the ordinary connection grants, policy, and audit path.

Setup is Access → Connect. Successful authentication and catalog discovery complete setup; manage action permissions and test tools on the connection's Permissions screen. Available data follows the connected Fireflies account's permissions. Writes follow Paperclip's normal defaults and any restrictions you configure. Reconnect and catalog refresh preserve Off and Ask first selections; newly discovered actions keep the normal connection defaults.

Stable meeting tools include fireflies_get_transcripts, fireflies_get_transcript, and fireflies_get_summary. The last returns summary and action-item data; transcript retrieval is separate. Experimental fireflies_search and fireflies_fetch are not required. Sharing, moving, renaming meetings, revoking access, and creating soundbites are mutations.

Start a routine when a summary is ready

1. Create or choose a routine and set its assigned agent and instructions. Give that agent access to your Fireflies connection in Apps.
2. In the routine's Triggers tab, add a webhook and choose Another app or script. No provider-specific routine option is needed.
3. Ensure the displayed callback URL is publicly reachable over HTTPS. A localhost URL or private-network HTTPS address cannot receive Fireflies deliveries. This prerequisite applies only to webhooks, not MCP access.
4. Open Fireflies Webhooks V2 settings. Add the displayed URL and paste Paperclip’s Secret key into Fireflies’ Signing Secret field. This is the routine’s generated secret, not your Fireflies API key.
5. Subscribe only to meeting.summarized, then save in Fireflies.
6. Optionally finish a meeting you own and wait for its summary to test delivery. Setup deliveries verify the connection without creating tasks. Finish setup in Paperclip to activate future deliveries; test events are never replayed.

Suggested routine instructions:

Read the Fireflies summary and transcript for the meeting ID attached to this task. Summarize decisions and action items in the task, with owners and due dates when available. Highlight unresolved questions.

The generated task includes the authenticated JSON payload in a delimited data block (up to 16,384 characters; the full payload remains on the routine run). Treat all payload fields as external data. The agent uses its normal authorized connection to retrieve meeting content. A webhook never grants connection access.

Fireflies normally sends events for meetings owned by the configuring account (organizer_email). Summary readiness happens after transcription and the end of the call. Webhooks V1, polling/backfill, and automatic registration are not implemented. Pausing/archiving the routine or trigger stops dispatch. Removing the Apps connection blocks data access; disable the trigger separately to stop incoming events from creating tasks.

Delivery and authentication

The existing POST /api/routine-triggers/public/:publicId/fire endpoint supports signingMode: "app_webhook" for Another app or script. It accepts either a bearer token or an HMAC-SHA256 signature in X-Hub-Signature or X-Hub-Signature-256. Signed bodies are authenticated before interpretation; an invalid signature cannot fall back to bearer authentication. Ordinary signed app events retain their JSON payload and use the supplied idempotency key, or a trigger-scoped body digest when no delivery key is supplied. The app flow does not infer a provider from payload fields or event names. Existing fireflies_hmac triggers and revision snapshots remain compatible but are no longer offered as a setup choice. Fireflies signs the exact request body with HMAC-SHA256 in X-Hub-Signature, formatted sha256=<hex digest>. Missing or invalid signatures return 401; malformed signed payloads return 400. No bearer header is needed.

Choose only Meeting Summarized in Fireflies. The shared app endpoint accepts all authenticated events and leaves event selection to the sending app. Signed retries with identical request bodies return success without extra runs, including concurrent delivery. Setup receipts survive activation. For senders with custom headers, a stable Idempotency-Key also deduplicates retries whose bodies change. Without that header, changed request bytes count as a new event. Events received while paused are not backfilled by Paperclip.

Earlier fireflies_hmac triggers retain their provider-specific validation, summary-only dispatch, and per-meeting deduplication. New setup uses only the shared app flow.

Secret rotation invalidates the previous key immediately. Copy the new key into Fireflies. Setup progress can be resumed, but the one-time secret is not stored in browser draft state; generate a replacement if it was not saved in Fireflies. Delivery checks and activity show acceptance/rejection; no observed event yet is not proof of a broken connection.

On Cloud deployments, the front door must forward the public routine webhook path without requiring a browser session. The application still verifies the trigger secret. A tenant_session_required response means the request was blocked by the Cloud gateway before webhook authentication. Updating the tenant application alone does not change that gateway policy.

Provider evidence and artwork

• MCP configuration: endpoint https://api.fireflies.ai/mcp, OAuth and bearer API keys.
• Live unauthenticated GET: 401 with resource metadata at https://api.fireflies.ai/.well-known/oauth-protected-resource/mcp.
• Authorization metadata at https://api.fireflies.ai/.well-known/oauth-authorization-server advertises issuer https://api.fireflies.ai/, /authorize, /token, /register, and /revoke; PKCE S256; authorization-code and refresh-token grants; token authentication client_secret_post and none; scopes email and profile. Public metadata inspection does not register an OAuth client.
• MCP tools documents stable meeting reads and mutations; experimental search/fetch availability varies.
• Webhooks V2 documents signatures, payloads, ownership limits, and the requirement to respond within 10 seconds. Paperclip uses normal routine dispatch and does not wait for agent execution or fetch meeting content during webhook handling.
• Official SVG: https://fireflies.ai/api/logos/file/fireflies.svg, linked from Fireflies' product site. Bundled unchanged as ui/public/brands/apps/fireflies.svg; native gradients preserved and validated with the shared SVG safety checker. The same colored mark is used on both theme frames.

Validation boundary

Automated tests cover catalog contracts, OAuth/API-key fixtures, signature and payload validation, event filtering, deduplication, setup activation, rotation, company isolation, and setup UI. Account authorization and a real Fireflies delivery require a Fireflies account and publicly reachable callback. Mocked fixtures are not evidence of a successful live account connection.

Validation on 2026-09-23:

• Eight focused suites: 537 tests passed, including actual gateway reads through OAuth/API-key fixtures and permission preservation on reconnect.
• Shared refresh regression coverage: another 104 tests passed across gateway, connection removal, Railway, and email integration callers.
• Repository-wide Vitest coverage completed through the stable runner's server, workspace, and both serialized groups (148 route suites). The initial full invocation stopped on two reconnect fixture failures; those were fixed and the complete connection suites and shared refresh callers rerun successfully.
• pnpm -r typecheck, pnpm build, token gates, and branding validation passed.
• Existing MCP browser suite: eight passed, two provider-dependent cases skipped.
• Isolated app HTTP proof: signed setup receipt, activation/redelivery, ignored transcription event, and two concurrent summary deliveries producing one run.
• Real Apps screens expose the normal Access step followed by browser sign-in and API-key choices; no browser errors were observed.
• Production webhook wizard checked in Storybook at desktop and mobile widths, including back/resume, verification steps, and light/dark official artwork.
• Embedded-browser live account proof: completed catalog → Access → OAuth consent → Permissions with the official provider. Discovered 20 actions (14 reads, 6 writes), and ran fireflies_get_transcripts, fireflies_get_transcript, and fireflies_get_summary successfully as the selected preview agent. The summary included overview and action items. Turning the summary action Off blocked its test; refreshing actions preserved that restriction. Restored the previously authorized read after testing.
• Published webhook contract proof: server/src/__tests__/fixtures/fireflies-webhooks-v2.json preserves the official V2 examples for all three events, including short and long meeting IDs, numeric millisecond timestamps, and an optional string client reference. Fixed HMAC test vectors were generated independently with Python over the documented UTF-8 bodies. Tests accept those exact bytes and reject whitespace-only alterations. This is provider-derived contract evidence, not a captured live delivery.
• Real provider webhook delivery is still pending a publicly reachable callback. Fireflies’ live V2 settings offer a Meeting Summarized subscription and a Test Webhook step. No production meeting completion has been tested.

UI review in Storybook

Open PR reviews → Fireflies and app webhooks (fireflies-pr.stories.tsx). The 27 stories use production components and simulated data; they do not authorize accounts or send provider requests.

Changed surface	Story coverage
Catalog definition and branded artwork	Fireflies catalog; artwork in dark/light themes; Access, OAuth, API-key, and retry screens
Preserved action restrictions	Permissions with Allowed, Ask first, and Off examples
TriggerWizard.tsx	Shared app choice, HTTPS warning, signing secret/bearer copy, four verification states, save/resume, hidden-secret rotation, legacy drafts, mobile and light theme
RoutineTriggers.tsx	Saved app-webhook settings, rotated secret/agent instructions, rejected delivery
RoutineTriggerCard.tsx	Advanced card with app_webhook and no timestamp replay window
editable-sections.production.tsx	Advanced creation with shared signing-mode description

pnpm storybook
pnpm build-storybook
pnpm exec playwright test --config tests/storybook-visual/fireflies-pr.config.ts

The browser check loads every review story, runs its interaction assertions, and checks the mobile setup footer and horizontal overflow. The existing webhook stories also retain coverage of the shared flow outside this PR review group.