Video & Moderation Events — Webhooks vs WebSockets

Applies to: Video, Moderation
Audience: All developers integrating Stream Video with Moderation

Quick Answer

• WebSocket events are delivered in real time to clients with an active WebSocket connection. Use them for live UI updates (e.g., showing a ringing indicator, updating participant counts).
• Webhook events are HTTP POST requests sent to your server endpoint. Use them for server-side processing (e.g., logging calls, triggering moderation workflows, analytics).
• Most video events are delivered via both channels. A few are exclusive to one:
  • connection.ok and connection.error are WebSocket only — they signal connection state to the client.
  • Several moderation events (moderation_check.completed, appeal.*, moderation_rule.triggered, etc.) are webhook only — they are meant for server-side processing.
• If you are not receiving an expected event, first confirm whether it is delivered via the channel you are listening on (WebSocket vs webhook).

Webhooks vs WebSockets — What's the Difference?

Video Events Reference

The table below lists all video (call.*) events and their delivery channels.

Call Lifecycle

Ringing & Notifications

Members & Permissions

Session & Participants

Recording

Broadcasting

Transcription & Closed Captions

User Actions

Video Moderation

Moderation Events Reference

If you use Stream Moderation alongside Video, the following moderation-specific events may also be relevant. Note that many moderation events are webhook only because they are designed for server-side moderation workflows.

Moderation - Both WebSocket & Webhook

Moderation - Webhook Only

WebSocket-Only Events

These events are never sent via webhooks. They are connection-state events relevant only to the connected client.

Why are these WebSocket only? They represent the state of a specific client connection. Your server does not have a “connection” to Stream in the same way — these events are meaningless outside the context of a live WebSocket session.

Webhook-Only Events

These events are never sent via WebSocket. They represent server-side moderation processing results that are not relevant to the end-user client in real time.

• moderation_check.completed — Indicates that an AI or rule-based moderation check has finished. Listen for this to take automated action on flagged content.
• moderation_rule.triggered — Fired when a rule builder rule matches. Use this to build custom moderation pipelines.
• appeal.created / appeal.accepted / appeal.rejected — Appeal lifecycle events. Use these to notify moderators or update your moderation dashboard.
• user.flagged / message.flagged / flag.updated — Flag lifecycle events for content and users.
• export.moderation_logs.success / export.moderation_logs.error — Async export completion notifications.

Common Pitfalls

1. “I'm not receiving moderation events on the client”

Most moderation events (moderation_check.completed, appeal.*, moderation_rule.triggered, etc.) are webhook only. They will never arrive over a WebSocket connection. Set up a webhook endpoint to receive them.

2. “I'm receiving duplicate events”

If you listen on both WebSocket and webhook for the same event type, you will receive it twice — once on each channel. This is by design. Either:

• Deduplicate using the event's created_at timestamp and type, or
• Use WebSocket for client-side logic and webhooks for server-side logic — don't mix responsibilities.

3. “I missed events while my client was disconnected”

WebSocket events are only delivered to connected clients. If a client disconnects and reconnects, it may miss events. Webhooks are more reliable for events you cannot afford to miss, since they include retry logic.

4. Confusing call.moderation_warning with moderation.flagged

• call.moderation_warning is a video event sent to call participants when a moderation action is taken during a live call (e.g., a warning overlay). It is delivered via both WebSocket and webhook.
• moderation.flagged is a moderation platform event fired when any item is flagged across the system. It is also delivered via both channels but carries different payload structure.

Best Practices

1. Use WebSocket for real-time UI. Show ringing indicators, participant joins/leaves, recording status, and moderation warnings to end users via WebSocket events.
2. Use webhooks for server-side logic. Log calls, process moderation results, trigger notifications, and build analytics pipelines using webhook events.
3. Always configure a webhook endpoint if you use moderation. Many moderation events are webhook-only, so without a webhook endpoint you will miss them entirely.
4. Verify webhook signatures. Always validate the X-Signature header using your API secret to ensure events are genuinely from Stream.
5. Deduplicate webhook deliveries. Use the X-Webhook-Id header to detect retried deliveries and avoid processing the same event twice.
6. Return 200 quickly from your webhook handler. Process events asynchronously. If your endpoint is slow to respond (over 6 seconds), Stream will retry, potentially causing duplicates.
7. Handle reconnection gracefully on WebSocket. When a client reconnects, query the current call state to catch up on any events missed during disconnection.

Diagnostics Checklist

If you are not receiving expected events, walk through this checklist:

1. Check the delivery channel. Is the event you expect delivered via WebSocket, webhook, or both? Refer to the tables above.
2. Verify your webhook is configured. Go to your Stream Dashboard → App Settings → Webhooks. Confirm the URL is correct and active.
3. Check webhook logs in the Dashboard. The Stream Dashboard shows recent webhook deliveries, including failures and response codes.
4. Verify the WebSocket connection. Confirm you receive connection.ok after connecting. If you get connection.error, fix your authentication first.
5. Check event subscriptions. Some events may be filtered by your app configuration. Verify the event type is enabled for webhook delivery in your Dashboard.
6. Check your webhook response time. If your endpoint takes longer than 6 seconds to respond, the delivery is considered failed and will be retried.
7. Look for signature validation errors. If your webhook handler rejects events, check that you are using the correct API secret for HMAC-SHA256 verification.