Webhooks and Events

MeetStream sends an HTTP POST with a JSON body to your server every time a bot changes state and when its recordings and transcripts are ready. This page is the reference for what arrives and how to handle it.

Where events are delivered

Both receive the same payloads. If you use both with the same URL, each event is delivered once, signed.

curl -X POST "https://api.meetstream.ai/api/v1/bots/create_bot" \
  -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",
    "custom_attributes": { "customer_id": "cus_123" }
  }'

Payload format

Bot status events look like this:

{
  "event": "bot.inmeeting",
  "bot_event": "bot.inmeeting",
  "bot_id": "6667fd0c-0165-471a-a880-06a1180be377",
  "bot_status": "InMeeting",
  "message": "Bot successfully joined the meeting",
  "status_code": 200,
  "timestamp": "2026-09-18T08:10:12.000000+00:00",
  "custom_attributes": { "customer_id": "cus_123" }
}

Post-call events use the same envelope but carry an artifact status instead of bot_status; see Post-call events.

The life of a bot

Platform details, such as how each platform’s lobby works, are in the Zoom, Google Meet and Microsoft Teams guides.

How a bot ends

A bot ends with exactly one ending event (the one exception, a bot you remove before it joins, is listed below). On the wire, event is always bot.stopped; bot_event names the cause:

Things that trip up handlers:

• A kick reports bot_status: "Stopped". Only bot_event: "bot.kicked" tells a kick apart from a normal stop.
• Google Meet join blockers carry a reason. When the meeting itself prevents the join, a Google Meet bot ends with bot_event: "bot.failed", bot_status: "Failed", status_code: 500 and a failure_reason: invalid_meeting_link, meeting_not_started, meeting_ended, meeting_restricted, sign_in_required, google_sign_in_failed or cant_join_call.
• A Zoom recording-permission denial ends with bot.stopped, after a bot.recording_permission_denied event.
• Removing a bot before it joins sets its status to Stopped without an ending webhook on Zoom and Google Meet.
• Workspace endpoints only receive the ending events they subscribe to. Subscribe to all five, or you will miss kicks, denials and lobby timeouts.

Every bot_status, error message and fix is listed in the status and error code reference.

Ending payloads

{
  "event": "bot.stopped",
  "bot_event": "bot.kicked",
  "bot_id": "6667fd0c-0165-471a-a880-06a1180be377",
  "bot_status": "Stopped",
  "message": "Bot was removed from the meeting by a participant",
  "status_code": 200,
  "timestamp": "2026-09-18T08:45:00.000000+00:00"
}

{
  "event": "bot.stopped",
  "bot_event": "bot.notallowed",
  "bot_id": "6667fd0c-0165-471a-a880-06a1180be377",
  "bot_status": "NotAllowed",
  "message": "Failed: Not admitted to meeting",
  "status_code": 500,
  "timestamp": "2026-09-18T08:20:00.000000+00:00"
}

{
  "event": "bot.stopped",
  "bot_event": "bot.failed",
  "bot_id": "6667fd0c-0165-471a-a880-06a1180be377",
  "bot_status": "Failed",
  "message": "Failed: Invalid meeting link",
  "status_code": 500,
  "failure_reason": "invalid_meeting_link",
  "timestamp": "2026-09-18T08:10:40.000000+00:00"
}

Post-call events

After the ending event, MeetStream processes the recording in the background. Audio, video and transcript processing run in parallel, so these events can arrive in any order. bot.done always comes last.

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

{
  "event": "bot.done",
  "bot_event": "bot.done",
  "bot_id": "6667fd0c-0165-471a-a880-06a1180be377",
  "bot_status": "Done",
  "message": "Post-call processing completed",
  "status_code": 200,
  "timestamp": "2026-09-18T09:07:30.000000+00:00"
}

About bot.done:

• It is the last event for a bot and always has status_code: 200. It means processing finished, not that every step succeeded. Check the artifact events for that.
• It is sent for bots that never got into the meeting too. For those, bot_status keeps the ending status (for example NotAllowed or Denied) instead of Done.
• It is sent whether or not transcription was configured, including for live (streaming) transcription.

data_deletion is sent when a bot’s media is deleted, either when its retention window ends or when you call DELETE /api/v1/bots/{bot_id}/delete. The bot’s status becomes MediaExpired and media endpoints stop returning files.

{
  "event": "data_deletion",
  "bot_event": "data_deletion",
  "bot_id": "5b0ff6e7-3cea-4c9f-a6b4-851c5f11cf4f",
  "status": "success",
  "message": "Bot data deleted successfully",
  "deleted_objects": 5,
  "status_code": 200,
  "timestamp": "2026-09-18T14:30:00Z"
}

Event catalog

These are all the event names MeetStream sends. The first four groups match the Subscribe to events list in the dashboard exactly. Events in the other groups are not listed in the dashboard and are delivered to every active workspace endpoint.

Live transcription results are not webhook events. They are posted to the live_transcription_required.webhook_url you set on the bot; see Live Transcription.

Signing

Deliveries to workspace endpoints carry:

Deliveries to a per-bot callback_url are not signed. Verification code for Python and Node is in Verifying Webhook Signatures.

Delivery rules

• One attempt, no automatic retries. A timeout, connection error or non-2xx response is logged as a failed delivery and is not retried. You can resend it from the dashboard: Webhooks > Logs > RESEND.
• Respond with 2xx quickly and process asynchronously. Some deliveries time out after 10 seconds, and a slow response can delay the next events for the same bot.
• At most once per bot: bot.inmeeting, the ending event and each post-call event. bot.joining can repeat for scheduled bots.
• No ordering guarantee between post-call events. Wait for bot.done if you need everything.
• Duplicates are possible when you resend from the Logs tab. De-duplicate on bot_id plus bot_event.
• Unknown event names can appear. Ignore events you do not handle rather than returning an error.

Handler checklist

1. Accept POST requests and read the raw body before parsing it, so you can verify the signature.
2. Verify X-MeetStream-Signature (workspace endpoints).
3. Return 2xx immediately; queue the work.
4. Branch on bot_event.
5. On any ending event (bot.stopped, bot.kicked, bot.denied, bot.notallowed, bot.failed), mark the session ended and record the cause.
6. On audio.processed, video.processed and transcription.processed, fetch the artifact. Or wait for bot.done and fetch everything at once.
7. On data_deletion, drop your stored references to the bot’s media.

Related: Workspace Webhook Endpoints, Set Up Local Server for Webhook, Debugging Bots, Bot status and error code reference.