Webhooks as the analytics layer your embedded video doesn’t ship with

Vendor analytics dashboards make a specific bet: that the metrics the vendor decided to expose are the ones the customer needs. The bet usually loses. Engineering rebuilds the dashboard on top of the underlying events anyway, because the dashboard never quite answers the question on the standup whiteboard.

We chose not to make that bet. The Digital Samba Embedded API exposes 22 webhook events, a JavaScript SDK with around 40 client-side events, and a live statistics endpoint that returns current-state snapshots. There is no built-in analytics dashboard. The trade is intentional: you build the analytics surface you actually need, on data primitives that are richer than what a one-size dashboard would expose.

Here is the architecture of that build and what each event source is good for.

The three event sources, ranked by reliability

Webhooks are server-emitted HTTP POST callbacks. The Digital Samba backend invokes a customer-configured endpoint when one of 22 events occurs. The transport is HTTP, the body is JSON, and the optional authorization_header secret is delivered as an Authorization Bearer token so the customer can verify the call is genuine. Webhooks are the server-of-record source: the event is captured server-side, and the customer's analytics pipeline can replay missed events from logs if the receiver endpoint was temporarily down.

SDK events are client-side, fired inside the browser via postMessage between the embedded iframe and the host page. There are around 40 of them, covering lifecycle, participant changes, media state, layout, and extension messages. These are useful for in-session UX: showing the user a live participant list, updating a custom toolbar, hooking a “raise hand” indicator into the host application. They are not useful as the system of record for analytics, because they only fire while the iframe is mounted on a connected participant’s device. Use them to enrich the host application’s UX, not to compute usage metrics.

The live statistics endpoint returns a current-state snapshot: which rooms are live right now, which participants are in a given room. It is poll-based: the customer asks, the API answers. Useful for dashboards that need a “right now” picture; not useful as the history of what happened. Combine it with webhooks for the historical layer.

The right mental model is webhooks for history and accounting, SDK events for in-session UX, live stats API for “now” views.

The 22 webhook events, grouped by analytics dimension

The full list groups into six clusters.

• Session lifecycle (5 events). session_started, session_ended, participant_joined, participant_left, participant_invited. These are the spine of any video usage analytics: session counts, durations, concurrent peaks, participant churn.
• Recording (3 events). recording_started, recording_stopped, recording_ready (the recording asset has been processed and is available for retrieval). Recording completion rate, mean time to availability, and post-meeting recording engagement are derivable from this cluster, plus file_processing_failed for failure cases.
• Content library (7 events). file_added_to_library, file_renamed, file_deleted_from_library, file_processing_failed, folder_added_to_library, folder_renamed, folder_deleted_from_library. Useful for tracking content production cadence and library hygiene.
• Telephony (3 events). phone_participant_muted, phone_participant_unmuted, phone_participant_asked_to_unmute. PSTN dial-in usage and remote-moderation pattern signal.
• Engagement (2 events). question_asked, question_answered. Q&A density per session is the practical engagement metric in webinar-style usage.
• Moderation (2 events). room_locked, room_unlocked. Manual moderation patterns and access control changes.

A few notable absences worth flagging. Quality-of-experience metrics — MOS scoring, adaptive bitrate transitions, connection error counts — are not in the webhook stream. They are surfaced through the SDK and through in-session diagnostics. If you want them in your analytics, you have to capture them client-side and post them to your own backend. Per-participant connection quality is in the same category.

Building a session analytics pipeline

The minimal viable structure for usage analytics from webhooks is roughly four components.

1. Receiver. An HTTP endpoint that accepts POST requests, verifies the Bearer token against the configured authorization_header secret, and acknowledges receipt with a 200 response as fast as possible. The endpoint should accept the payload and return; processing happens out of band. Slow acknowledgements lead to redelivery from any well-behaved webhook source, and synchronous processing inside the receiver is the most common cause of duplicate-event problems downstream.
2. Idempotency layer. Webhook deliveries can repeat. The receiver needs to recognise duplicates and deduplicate based on the event’s identifying fields. The cheapest implementation is a unique key on a tuple of event type, session identifier, participant identifier, and event timestamp, and a rejected-duplicate on insert.
3. Store-then-process. Persist the raw webhook payload before doing any transformation. The analytics derivations evolve over time; the raw event log is durable. Storing immutably means you can re-derive a year of metrics when the product question changes, instead of replaying webhooks you no longer have.
4. Derivations. From session lifecycle events you derive session count, duration distribution, concurrent participant peaks, and participant churn. From recording events you derive recording completion rate and time-to-availability. From engagement events you derive Q&A density and response latency. From telephony events you derive PSTN usage share. None of these is computed by us; all of them are computable from what we send.

For higher reliability, add an out-of-band reconciliation: periodically pull the live statistics endpoint and the recordings list endpoint, compare against the webhook-derived state, and flag drift. Webhook delivery is reliable but not infallible; a reconciliation job catches missed events without requiring expensive replay infrastructure.

What webhooks can’t tell you (and how to fill the gap)

Three categories of metric need additional sources.

1. Per-session connection quality. MOS scores, adaptive bitrate adjustments, packet loss, jitter — these are session-internal and surfaced through the SDK and in-session diagnostics. To get them into your analytics, capture them client-side from the SDK event stream and post them to your own backend. The pattern is the same as third-party real-user monitoring: instrument the client, sample, batch, send.
2. Recording engagement. Whether the recording was watched, by whom, for how long, where viewers dropped off — none of this is in the webhook stream because it happens outside the video session entirely. You build it where the recording is hosted, in your own player or library surface.
3. User-level cross-session activity. “Which of our customers had the most meetings last month” is derivable from webhooks if you can resolve participant identifiers to your own user identifiers, which you provide at session creation through the SDK or room configuration. The webhook layer gives you the events; the join to your user model is your job.

These are not gaps in the sense of missing primitives; they are gaps in the sense of work that has to happen on your side because the data lives on your side.

Why this is the right architecture, even when it is annoying

The shorter story is that we ship the data, not the UI. Three reasons that survives scrutiny.

• You own the data model. The dashboard you build maps cleanly onto your product’s existing analytics surface — your dimensions, your filters, your aggregation grain, your retention policy. A vendor dashboard never does.
• You control retention, residency, and lifecycle. Webhook payloads land in your infrastructure. They are subject to your data-handling rules, your GDPR documentation, your data-subject-rights pipeline. A vendor dashboard adds an external place where your usage data lives; the webhook pattern keeps it inside your perimeter.
• You survive product pivots. Vendor dashboards get redesigned, deprecated, replaced. A vendor’s analytics surface is the part of the product most likely to change in the next eighteen months. Webhooks change rarely and additively; new events ship as new event types, not as breaking changes to existing ones.
• The trade is that you have to write code on the receiver side that you would not have to write if a dashboard came in the box. That cost is real on month one and amortised by month three.

If you want to see the actual surface: the webhooks reference covers the 22 event types, the payload structure, the authorization header pattern, and the management endpoints. The SDK event taxonomy is in the SDK reference.