MeetStream Guide: Webhook Events

This guide explains how to receive webhook events from MeetStream, what each event means, and how to trigger follow-up actions like fetching audio, video, or transcription.

Applies to: Google Meet, Zoom, Microsoft Teams.
Support: docs.meetstream.ai • API: api.meetstream.ai

1) Add your webhook URL while creating the bot

When you create a bot, include your webhook endpoint in the payload as:

1
{
2
  "callback_url": "{{webhook_url}}"
3
}

MeetStream will send HTTP POST requests to your callback_url whenever the bot’s status changes during its lifecycle and when post-call processing completes.

Example (Create Agent + callback_url)

Docs: https://docs.meetstream.ai/api-reference/api-reference/bot-endpoints/create-agent

$
curl -X POST "https://api.meetstream.ai/api/v1/bots/create_agent" \
>
  -H "Authorization: Token <YOUR_API_KEY>" \
>
  -H "Content-Type: application/json" \
>
  -d '{
>
    "meeting_link": "<YOUR_MEETING_LINK>",
>
    "video_required": false,
>
    "callback_url": "https://your-domain.com/webhooks/meetstream"
>
  }'

Tip: Your webhook should respond quickly with 2xx (e.g., 200) to acknowledge receipt.

2) Webhook payload format

Every webhook notification follows this structure:

1
{
2
  "event": "bot.joining",
3
  "bot_id": "6667fd0c-0165-471a-a880-06a1180be377",
4
  "bot_status": "Joining",
5
  "message": "Bot is joining the meeting",
6
  "status_code": 200,
7
  "timestamp": "2026-02-27T07:11:51.863543+00:00",
8
  "custom_attributes": {}
9
}

Fields

• event — event type (see below)
• bot_id — unique identifier for the bot session
• bot_status — status detail (see Status Reference)
• message — human readable explanation
• status_code — always 200
• timestamp — ISO-8601 timestamp
• custom_attributes — echoed back if you provided it when creating the bot

3) Event types (what you’ll receive)

MeetStream sends two categories of webhook events: bot lifecycle events and post-call processing events.

A) Bot lifecycle events

These events track the bot’s presence in the meeting:

Important notes:

• Every bot starts with bot.joining.
• If the bot joins successfully, you will receive bot.inmeeting.
• The lifecycle ends with exactly one bot.stopped event.
• If the bot fails to join (timeout/denied/error), you may get bot.stopped right after bot.joining without a bot.inmeeting.

B) Post-call processing events

After bot.stopped, MeetStream continues processing the recorded session in the background. You will receive additional webhook events as each artifact finishes processing:

These events arrive asynchronously after the bot has stopped — the order and timing depend on processing duration for each artifact.

Example payloads

audio.processed

1
{
2
  "bot_id": "5b0ff6e7-3cea-4c9f-a6b4-851c5f11cf4f",
3
  "event": "audio.processed",
4
  "audio_status": "Success",
5
  "message": "Audio processing completed successfully",
6
  "status_code": 200
7
}

transcription.processed

1
{
2
  "bot_id": "5b0ff6e7-3cea-4c9f-a6b4-851c5f11cf4f",
3
  "event": "transcription.processed",
4
  "transcript_status": "Success",
5
  "message": "Transcript processing completed successfully",
6
  "status_code": 200
7
}

video.processed

1
{
2
  "bot_id": "5b0ff6e7-3cea-4c9f-a6b4-851c5f11cf4f",
3
  "event": "video.processed",
4
  "video_status": "Success",
5
  "message": "Video processing completed successfully",
6
  "status_code": 200
7
}

data_deletion

1
{
2
  "bot_id": "5b0ff6e7-3cea-4c9f-a6b4-851c5f11cf4f",
3
  "event": "data_deletion",
4
  "status": "success",
5
  "message": "Bot data deleted successfully",
6
  "deleted_objects": 5,
7
  "timestamp": "2024-01-15T14:30:00Z",
8
  "status_code": 200
9
}

4) Status reference (bot_status)

bot_status gives more detail, especially for bot.stopped.

5) Recommended actions based on webhook events

Your server can react to webhook events and run follow-up workflows.

A) On bot.inmeeting

Typical actions:

• Update your UI/state: “bot is live”
• Start timers / internal tracking
• Notify other systems that recording has started

B) On bot.stopped (terminal)

This is the moment to mark the session as complete. Artifacts may still be processing at this point.

Recommended flow:

1. Receive bot.stopped
2. Read bot_status
3. If bot_status is Stopped (normal exit), wait for processing events before fetching outputs.
4. If bot_status is NotAllowed / Denied / Error, log the reason (message) and alert/handle accordingly.

C) On post-call processing events

Once you receive audio.processed, transcription.processed, or video.processed, the corresponding artifact is ready to fetch:

• Audio: https://docs.meetstream.ai/api-reference/api-reference/bot-endpoints/get-bot-audio
• Video: https://docs.meetstream.ai/api-reference/api-reference/bot-endpoints/get-bot-video

D) On data_deletion

Confirms that bot data has been removed. Update your records accordingly — further fetch requests for this bot’s artifacts will fail.

6) Webhook signing (optional but recommended)

If you configure a webhook secret, MeetStream includes an HMAC signature in headers:

• X-MeetStream-Signature: sha256=<hex_digest>
• X-MeetStream-Timestamp: ISO 8601 timestamp

Verification steps:

1. Compute HMAC-SHA256(your_secret, raw_request_body)
2. Compare with X-MeetStream-Signature (strip sha256= prefix)
3. Optionally validate timestamp is within an acceptable window (replay protection)

7) Retry behavior (important)

• Webhook delivery is best-effort.
• If your endpoint returns a non-2xx, the webhook is not retried.
• A bot may send up to 3 bot.joining events if join retries are configured.
• bot.inmeeting and bot.stopped are sent at most once.
• Post-call processing events (audio.processed, transcription.processed, video.processed, data_deletion) are sent at most once.

8) Minimal webhook handler checklist

• ✅ Accept POST requests at callback_url
• ✅ Verify signature (if enabled)
• ✅ Always respond 2xx quickly
• ✅ Idempotent handling (store processed event IDs or de-dupe by {bot_id, event, timestamp})
• ✅ On bot.stopped, mark session complete
• ✅ On audio.processed / video.processed / transcription.processed, fetch the corresponding artifact
• ✅ On data_deletion, clean up local references

If you want, share your preferred stack (Node/FastAPI/Cloudflare Workers), and I’ll provide a ready-to-paste webhook handler example.