Zoom Team Chat Webhook V2: Architecture, Events, and the Video-First Messaging Gap

Zoom's Dual Identity: Video Platform With a Chat Layer

Zoom is unambiguously the dominant enterprise video conferencing platform. Zoom Team Chat — the persistent messaging layer that Zoom has been developing since 2021 as a competitor to Slack — is a secondary product for most organizations.

This market position has a technical consequence: Zoom Team Chat exists in an architectural context where video is the primary event stream and chat is the secondary one. The Webhook V2 system was designed primarily around meeting lifecycle events (meeting started, participant joined, recording completed) and has been extended to cover chat events.

Understanding this heritage helps integration engineers anticipate where Zoom Team Chat's API is mature and where it has rough edges.

Zoom's Webhook V2 Architecture

Authentication: Header Verification

Zoom's Webhook V2 system authenticates webhook deliveries using a token-based header verification model. When a webhook event is delivered to your endpoint:

1. Zoom sends the event payload with a x-zm-signature header
2. The signature is an HMAC-SHA256 hash of v0:{timestamp}:{raw_payload} using your webhook Secret Token
3. Your endpoint verifies the signature before processing the event

This is a robust delivery authentication mechanism — it prevents replay attacks (the timestamp component) and ensures the payload was not modified in transit. The implementation is similar to Slack's webhook signature verification.

Event delivery reliability

Zoom's Webhook V2 system has materially better delivery reliability characteristics than the legacy V1 system:

• Delivery guarantees: Zoom attempts delivery with exponential backoff on failures
• Retry window: Failed deliveries are retried for up to 24 hours
• Response timeout: Your endpoint must respond within 3 seconds with a 200 status
• Verification challenge: On subscription creation, Zoom sends a verification challenge that your endpoint must echo back (same pattern as Slack)

The Validation Endpoint Event

When creating a Zoom webhook subscription, the first event delivered is a validation challenge:

{
  "payload": {
    "plainToken": "qgg8l9RE9MusEeGfxLJlkA"
  },
  "event_ts": 1617000000000,
  "event": "endpoint.url_validation"
}

Your endpoint must respond with:

{
  "plainToken": "qgg8l9RE9MusEeGfxLJlkA",
  "encryptedToken": "<HMAC-SHA256 of plainToken using Secret Token>"
}

Chat-Specific Events

For a Zoom Team Chat bridge, the relevant event types are:

The chat_message.sent payload includes the message text, sender information (user ID, display name), channel ID, and a message timestamp that functions as a unique identifier.

The file attachment gap

Zoom Team Chat file attachments are a known integration pain point. The chat_message.sent event for a file upload provides a download URL — but this URL requires authentication with Zoom OAuth credentials to access. The file cannot be fetched without a valid Zoom access token.

For a cross-platform file transfer, the bridge must:

1. Receive the chat_message.sent event with the file URL
2. Authenticate and download the file from Zoom using the OAuth token
3. Upload the file to the destination platform (Slack Files API, Microsoft Graph Files endpoint)
4. Post the message to the destination channel with the new file reference

This multi-step file transfer sequence is where many low-quality Zoom integrations fail — they either skip file transfer entirely or expose pre-signed Zoom file URLs in the destination platform (which expire and become inaccessible).

The Meeting-to-Chat Event Flow

Where Zoom's integration architecture truly shines is in the meeting lifecycle → chat event flow. This is the use case Zoom's webhook system was designed for.

A typical meeting-complete workflow:

1. meeting.ended event fires with meeting ID, duration, participant list
2. recording.completed event fires (if cloud recording was enabled) with recording URLs, transcript URL
3. SyncRivo processes both events, assembles an Adaptive Card / Slack Block Kit message with meeting summary
4. Pushes the summary to the designated Teams/Slack channel for post-meeting action items

This workflow is where Zoom excels as an integration target — the events are well-structured, the payload is rich, and the latency between meeting end and recording.completed event is typically under 5 minutes for standard recordings.

OAuth and API Authentication

Zoom's API uses OAuth 2.0 with either Server-to-Server OAuth (for backend integrations) or User-managed OAuth apps.

For a messaging bridge, Server-to-Server OAuth is the correct authentication model:

1. Create a Server-to-Server OAuth app in the Zoom Marketplace
2. Grant account-level scopes for the required API access
3. Exchange client credentials for an access token at https://zoom.us/oauth/token?grant_type=account_credentials
4. Access tokens expire after 1 hour and must be refreshed

The relevant scopes for a chat bridge:

• chat_channel:read:admin — list and read channels
• chat_message:read:admin — read message history
• chat_message:write:admin — post messages to channels
• user:read:admin — resolve user identities

The :admin suffix indicates these are account-level scopes that require account admin approval when the app is installed in a Zoom account.

Rate Limits

Zoom's API rate limits vary by endpoint and account type. For chat operations on a paid account:

• chatmessages:POST (send message): 10 requests per second per user
• chatmessages:GET (read messages): 30 requests per second

These are generous limits for a messaging bridge. Zoom's rate limiting is less likely to be a bottleneck than Teams or Slack for typical enterprise message volumes.

The Identity Mapping Challenge

Zoom users are identified by their Zoom user ID — a numeric identifier that is not the same as their email address or their identity on other platforms. For cross-platform identity attribution (showing "Jordan Hayes" rather than "SyncRivo Bridge" as the sender), the bridge must maintain a user ID map:

• Zoom user ID → email address (resolved via Zoom Users API)
• Email address → Slack user ID / Teams AAD object ID

This cross-platform identity map is initialized when the bridge is first configured and updated incrementally as new participants are encountered.

See Zoom integration pages → | Read the full Zoom-Teams integration guide →