Webhooks

Webhooks let your application receive real-time HTTP notifications when events happen in Mavio. Instead of polling the API for changes, register a webhook endpoint and Mavio pushes event data to you as it happens.

Setting up a webhook

Open webhook settings

Navigate to Settings > Developer > Webhooks and click Add Endpoint.

Configure the endpoint

Provide:

URL — the HTTPS endpoint where Mavio sends events (must be publicly accessible)
Events — select which events trigger this webhook (see event types below)
Description — optional label for this endpoint

Receive the signing secret

Mavio generates a signing secret for this endpoint. Copy it and store it securely. You use this to verify that incoming requests are genuinely from Mavio.

Test the endpoint

Click Send Test Event to verify your endpoint receives and responds correctly. Mavio sends a ping event and expects a 200 response.

Use a service like webhook.site during development to inspect incoming payloads before building your handler.

Event types

Event	Trigger	Payload includes
`meeting.started`	A meeting recording begins	Meeting ID, title, participants, recording method
`meeting.completed`	A meeting recording ends	Meeting ID, title, duration, participant count
`transcript.ready`	Transcription is complete	Meeting ID, transcript ID, language, word count
`summary.ready`	AI summary is generated	Meeting ID, summary text, key topics
`action_items.ready`	Action items are extracted	Meeting ID, action items array with assignees
`minutes.ready`	Meeting minutes are generated	Meeting ID, minutes content
`diagram.ready`	A diagram has been generated	Meeting ID, diagram ID, diagram type
`speaker.identified`	A new speaker is identified	Meeting ID, speaker profile ID, confidence
`meeting.shared`	A meeting is shared	Meeting ID, shared with user ID, permission level
`meeting.deleted`	A meeting is deleted	Meeting ID, deleted by user ID

meeting.completed payload example

{
  "id": "evt_a1b2c3d4e5f6",
  "type": "meeting.completed",
  "created_at": "2026-04-14T15:30:00Z",
  "data": {
    "meeting_id": "mtg_abc123",
    "title": "Product Roadmap Review",
    "duration_seconds": 2700,
    "participant_count": 5,
    "recording_method": "system_audio",
    "workspace_id": "ws_xyz789"
  }
}

transcript.ready payload example

{
  "id": "evt_f6e5d4c3b2a1",
  "type": "transcript.ready",
  "created_at": "2026-04-14T15:35:00Z",
  "data": {
    "meeting_id": "mtg_abc123",
    "transcript_id": "trs_def456",
    "language": "en",
    "word_count": 8420,
    "speaker_count": 5,
    "duration_seconds": 2700
  }
}

action_items.ready payload example

{
  "id": "evt_x9y8z7w6v5u4",
  "type": "action_items.ready",
  "created_at": "2026-04-14T15:36:00Z",
  "data": {
    "meeting_id": "mtg_abc123",
    "action_items": [
      {
        "id": "ai_001",
        "text": "Send updated proposal to client",
        "assignee": "Alice Johnson",
        "due_date": "2026-04-18",
        "priority": "high"
      },
      {
        "id": "ai_002",
        "text": "Schedule follow-up meeting with engineering",
        "assignee": "Bob Smith",
        "due_date": null,
        "priority": "medium"
      }
    ]
  }
}

Payload format

All webhook payloads follow this structure:

{
  "id": "evt_unique_event_id",
  "type": "event.type",
  "created_at": "2026-04-14T10:30:00Z",
  "data": { }
}

HTTP headers

Each webhook request includes the following headers:

Content-Type: application/json
X-Mavio-Signature: sha256=xxxxxxxxxxxxxxxx
X-Mavio-Event: meeting.completed
X-Mavio-Delivery: dlv_unique_id
X-Mavio-Timestamp: 1713105000

Signature verification

Verify webhook signatures to ensure requests are genuinely from Mavio. Each request includes an HMAC-SHA256 signature in the X-Mavio-Signature header.

import hmac
import hashlib

def verify_webhook(payload_body: bytes, signature: str, secret: str) -> bool:
    expected = hmac.new(
        secret.encode(), payload_body, hashlib.sha256
    ).hexdigest()
    return hmac.compare_digest(f"sha256={expected}", signature)

import crypto from 'crypto';

function verifyWebhook(payloadBody, signature, secret) {
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payloadBody)
    .digest('hex');
  return crypto.timingSafeEqual(
    Buffer.from(`sha256=${expected}`),
    Buffer.from(signature)
  );
}

Always verify webhook signatures before processing the payload. Without verification, an attacker could send fake events to your endpoint.

Retry logic

If your endpoint does not return a 2xx response, Mavio retries the delivery with exponential backoff:

Attempt	Delay
1st retry	1 minute
2nd retry	5 minutes
3rd retry	30 minutes
4th retry	2 hours
5th retry	12 hours

After 5 failed attempts, the delivery is marked as failed. You can view and manually retry failed events from Settings > Developer > Webhooks > [Endpoint] > Deliveries.

If an endpoint consistently fails (10+ consecutive failures), Mavio disables it and sends an email notification. Re-enable it from the webhook settings after fixing the issue.

Troubleshooting

Endpoint not receiving events

Verify the URL is publicly accessible over HTTPS. Check that your server responds with a 200 status within 10 seconds. Use the Send Test Event button to debug.

Signature verification failing

Ensure you are comparing against the raw request body (not a parsed/re-serialized version). The signature is computed over the exact bytes sent by Mavio.

Duplicate events

Webhook deliveries are at-least-once. Your endpoint may receive the same event more than once during retries. Use the X-Mavio-Delivery header as an idempotency key to deduplicate.

What IP addresses do webhooks come from?

Mavio sends webhooks from a fixed set of IP addresses listed in the webhook settings page. You can allowlist these in your firewall.

Can I pause webhooks temporarily?

Yes. Toggle the Active switch on any endpoint to pause deliveries. Events that occur while paused are not queued and are skipped.

Get Started

Meeting Recording

AI Features

Notes & Templates

Channels & Collaboration

Integrations

Apps & Platforms

Account & Billing

Developer

Privacy & Security

Troubleshooting

Setting up a webhook

Event types

Payload format

HTTP headers

Signature verification

Retry logic

Troubleshooting

​Setting up a webhook

​Event types

​Payload format

​HTTP headers

​Signature verification

​Retry logic

​Troubleshooting

Setting up a webhook

Event types

Payload format

HTTP headers

Signature verification

Retry logic

Troubleshooting