Overview
Webhooks V2 provides an improved webhook system with granular event subscriptions and enhanced security. You can subscribe to specific meeting lifecycle events and receive real-time notifications at your configured endpoint.Webhooks V2 replaces the legacy webhook system. Webhooks V1 is deprecated and its Developer settings field is read-only, so all new webhooks - including team-wide Super Admin webhooks - are created here.
Events Supported
Webhooks V2 supports the following events:You can subscribe to one or more events per webhook. Only events you subscribe to will be delivered. The Event Subscriptions list on the setup page is the source of truth for which events are currently available.
Setting Up Webhooks V2
1
Visit the Webhooks V2 configuration page
2
Enter a valid HTTPS URL that accepts POST requests in the Webhook URL field
3
Optionally, enter a Signing Secret for payload signature verification
4
Under Event Subscriptions, select the events you want to subscribe to
5
Save your configuration
6
Click Send Test Event to confirm your endpoint is reachable and validating payloads correctly
Webhooks are delivered for meetings you own. If you are a Super Admin on an Enterprise team, events for all meetings owned by your team are also escalated to your webhook - see Super Admin.
Webhook Payload
Each webhook notification is sent as aPOST request with a JSON payload containing the following fields:
String
required
The event type that triggered the webhook (e.g.,
meeting.transcribed, meeting.summarized, meeting.bot_joined)Number
required
Unix timestamp in milliseconds indicating when the event was fired
String
required
Identifier for the meeting that the event relates to. This is the same as the transcript ID used throughout the Fireflies API.
String
Custom identifier set by you during upload. Use this to correlate webhook events with your uploads.
Example Payloads
Meeting TranscribedWebhook Authentication
Webhooks V2 uses HMAC-SHA256 signatures to verify that webhook payloads originate from Fireflies and have not been tampered with in transit.How It Works
Each webhook request includes anX-Hub-Signature header containing a SHA-256 HMAC signature of the request body. The signature is computed using the signing secret you configured during setup.
The signature format is:
Verifying the Signature
1
Extract the
X-Hub-Signature header from the incoming request2
Compute the HMAC-SHA256 digest of the raw request body using your signing secret
3
Prefix the hex-encoded digest with
sha256=4
Compare the computed signature with the header value using a timing-safe comparison
Verification Examples
Request Headers
Each webhook delivery includes the following headers:Delivery Behavior
- Webhooks are sent as
POSTrequests to your configured URL. The URL must use HTTPS and resolve to a public host; redirects are not followed - Your endpoint must respond with a
2xxstatus code within 30 seconds of the request starting to be considered successful; the TCP connection itself must be established within 10 seconds - Failed deliveries are retried up to 5 times with a growing backoff - 30 seconds, 2 minutes, 10 minutes, 30 minutes and 2 hours - so a transient outage of up to ~3 hours is recovered automatically
- Retries apply to transient failures: failures to connect (connect timeouts, DNS failures, refused or reset connections), unclassified network errors,
429responses and5xxresponses. Other4xxresponses, TLS/certificate errors and invalid URLs are treated as permanent failures and are not retried - If the connection succeeds but your server does not respond within 30 seconds, the delivery is marked failed and not retried: your server most likely received the request, so a retry would duplicate it
Migrating from Webhooks V1
If you are using the legacy webhooks system, here is a summary of the key differences:Migration Steps
1
Go to the Webhooks V2 setup page
2
Enter your existing webhook URL
3
If you used a signing secret, enter it in the Signing Secret field
4
Select the events you want to subscribe to (choose
meeting.transcribed for equivalent V1 behavior)5
Save and update your webhook consumer to handle the new payload format and signature header
FAQ
What is the difference between meeting.transcribed and meeting.summarized?
What is the difference between meeting.transcribed and meeting.summarized?
meeting.transcribed fires when the raw transcript is ready and available for viewing. meeting.summarized fires after the AI-generated summary (including action items, notes, and other insights) has been processed.What is meeting.bot_joined used for?
What is meeting.bot_joined used for?
meeting.bot_joined fires when the Fred bot successfully joins a meeting. This is useful for triggering real-time workflows as soon as the bot is in the call.Can I subscribe to multiple events?
Can I subscribe to multiple events?
Yes. You can select one or more events during setup. Only events you subscribe to will trigger webhook deliveries.
Why am I not receiving webhook notifications?
Why am I not receiving webhook notifications?
- Webhooks are only fired for meetings you own (i.e., you are the
organizer_email). - Ensure your endpoint accepts POST requests and responds with a 2xx status code within 30 seconds.
- Verify that you have subscribed to the correct events.
- If using signature verification, ensure your signing secret matches what is configured.
Team-wide webhooks are only supported for the Enterprise tier with the Super Admin role. This allows you to setup one webhook for all meetings owned by your team. Details here.
Do I need to migrate from Webhooks V1?
Do I need to migrate from Webhooks V1?
Existing V1 webhooks continue to be delivered, but V1 is deprecated and new V1 webhooks can no longer be saved. Migrate when convenient to get granular event subscriptions and the current payload format.
What about the webhook URL passed to uploadAudio?
What about the webhook URL passed to uploadAudio?
The optional
webhook field on the uploadAudio mutation still works and still delivers the legacy V1 payload shape (meetingId, eventType) for that single upload. It is independent of your saved V2 webhook.Additional Resources
Webhooks V1
Legacy webhook documentation
Upload Audio
Use the API to upload audio to Fireflies.ai