Webhook Events Documentation

Meeting BaaS sends webhook events to your configured webhook URL when specific events occur.

Webhook Event Types

1. complete

Sent when a bot successfully completes recording a meeting. Contains full transcription data and a link to the recording.

{
  \"event\": \"complete\",
  \"data\": {
    \"bot_id\": \"123e4567-e89b-12d3-a456-426614174000\",
    \"event_uuid\": \"123e4567-e89b-12d3-a456-426614174001\",
    \"transcript\": [
      {
        \"speaker\": \"John Doe\",
        \"offset\": 1.5,
        \"start_time\": 1.5,
        \"end_time\": 2.4,
        \"words\": [
          {
            \"start\": 1.5,
            \"end\": 1.9,
            \"word\": \"Hello\"
          },
          {
            \"start\": 2.0,
            \"end\": 2.4,
            \"word\": \"everyone\"
          }
        ]
      }
    ],
    \"speakers\": [
      \"Jane Smith\",
      \"John Doe\"
    ],
    \"mp4\": \"https://storage.example.com/recordings/video123.mp4?token=abc\",
    \"audio\": \"https://storage.example.com/recordings/audio123.wav?token=abc\",
    \"event\": \"complete\",
    \"extra\": {
      \"foo\": \"bar\"
    }
  }
}

The complete event includes:

• bot_id: Unique identifier for the bot that completed recording
• event_uuid: UUID of the calendar event (if this bot was created from an event)
• speakers: A set of speaker names identified in the meeting
• transcript: Full transcript data with speaker identification and word timing
• mp4: URL to the recording file (valid for 24 hours by default)
• event: Event type identifier ("complete")

2. failed

Sent when a bot fails to join or record a meeting. Contains error details.

{
  \"event\": \"failed\",
  \"data\": {
    \"bot_id\": \"123e4567-e89b-12d3-a456-426614174000\",
    \"event_uuid\": \"123e4567-e89b-12d3-a456-426614174001\",
    \"error\": \"meeting_not_found\",
    \"message\": \"Could not join meeting: The meeting ID was not found or has expired\",
    \"extra\": {
      \"foo\": \"bar\"
    }
  }
}

The failed event includes:

• bot_id: Unique identifier for the bot that failed
• event_uuid: UUID of the calendar event (if this bot was created from an event)
• error: Error code identifying the type of failure
• message: Detailed human-readable error message

Common error types include:

• meeting_not_found: The meeting ID or link was invalid or expired
• access_denied: The bot was denied access to the meeting
• authentication_error: Failed to authenticate with the meeting platform
• network_error: Network connectivity issues during recording
• internal_error: Internal server error

3. calendar.sync_events

Sent when calendar events are synced. Contains information about which events were updated.

{
  \"event\": \"calendar.sync_events\",
  \"data\": {
    \"calendar_id\": \"123e4567-e89b-12d3-a456-426614174000\",
    \"last_updated_ts\": \"2023-05-01T12:00:00Z\",
    \"affected_event_uuids\": [
      \"123e4567-e89b-12d3-a456-426614174001\",
      \"123e4567-e89b-12d3-a456-426614174002\"
    ]
  }
}

The calendar.sync_events event includes:

• calendar_id: UUID of the calendar that was synced
• last_updated_ts: ISO-8601 timestamp of when the sync occurred
• affected_event_uuids: Array of UUIDs for calendar events that were added, updated, or deleted

This event is triggered when:

• Calendar data is synced with the external provider (Google, Microsoft)
• Multiple events may be created, updated, or deleted in a single sync operation
• Use this event to update your local cache of calendar events

4. transcription_complete

Sent when transcription is completed separately from recording (e.g., after retranscribing).

{
  \"event\": \"transcription_complete\",
  \"data\": {
    \"bot_id\": \"123e4567-e89b-12d3-a456-426614174000\"
  }
}

The transcription_complete event includes:

• bot_id: Unique identifier for the bot with the completed transcription

This event is sent when:

• You request a retranscription via the /bots/retranscribe endpoint
• An asynchronous transcription process completes after the recording has ended

Setting Up Webhooks

You can configure webhooks in two ways:

1. Account-level webhook URL: Set a default webhook URL for all bots in your account using the /accounts/webhook_url endpoint
2. Bot-specific webhook URL: Provide a webhook_url parameter when creating a bot with the /bots endpoint

Your webhook endpoint must:

• Accept POST requests with JSON payload
• Return a 2xx status code to acknowledge receipt
• Process requests within 10 seconds to avoid timeouts
• Handle each event type appropriately based on the event type

All webhook requests include:

• x-meeting-baas-api-key header with your API key for verification
• content-type: application/json header
• JSON body containing the event details

Webhook Reliability

If your endpoint fails to respond or returns an error, the system will attempt to retry the webhook delivery. For critical events, we recommend implementing:

• Idempotency handling to prevent duplicate processing of the same event
• Proper logging of webhook receipts for audit purposes
• Asynchronous processing to quickly acknowledge receipt before handling the event data

For security, always validate the API key in the x-meeting-baas-api-key header matches your API key.

curl -X GET "https://api.meetingbaas.com/bots/webhooks"

null