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

1

Open webhook settings

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

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
3

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.
4

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

EventTriggerPayload includes
meeting.startedA meeting recording beginsMeeting ID, title, participants, recording method
meeting.completedA meeting recording endsMeeting ID, title, duration, participant count
transcript.readyTranscription is completeMeeting ID, transcript ID, language, word count
summary.readyAI summary is generatedMeeting ID, summary text, key topics
action_items.readyAction items are extractedMeeting ID, action items array with assignees
minutes.readyMeeting minutes are generatedMeeting ID, minutes content
diagram.readyA diagram has been generatedMeeting ID, diagram ID, diagram type
speaker.identifiedA new speaker is identifiedMeeting ID, speaker profile ID, confidence
meeting.sharedA meeting is sharedMeeting ID, shared with user ID, permission level
meeting.deletedA meeting is deletedMeeting ID, deleted by user ID
{
  "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": "meeting_bot",
    "workspace_id": "ws_xyz789"
  }
}

{
  "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
  }
}

{
  "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)
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:
AttemptDelay
1st retry1 minute
2nd retry5 minutes
3rd retry30 minutes
4th retry2 hours
5th retry12 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

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.
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.
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.
Mavio sends webhooks from a fixed set of IP addresses listed in the webhook settings page. You can allowlist these in your firewall.
Yes. Toggle the Active switch on any endpoint to pause deliveries. Events that occur while paused are not queued and are skipped.