Embed & Usage Events
Events for blocked embeds, invalid tokens, and storage/bandwidth quota alerts.
These events cover two areas: embed security (blocked referrers and rejected telemetry tokens) and usage quotas (storage and bandwidth thresholds). For the envelope format, shared headers, and retry policy, see Outbound Webhooks.
Examples reuse the following placeholders throughout this page:
organization_id → 11111111-1111-1111-1111-111111111111,
video id → 00000000-0000-4000-8000-00000000aa01.
embed.blocked
When it fires. The embed HTML was requested but the effective referrer was rejected by the referrer policy configured for the video (domain not in the allowed list).
{
"id": "evt_b2c3d4e5-f6a7-4890-b123-456789abcdef",
"type": "embed.blocked",
"created_at": "2026-05-09T23:00:00.000Z",
"organization_id": "11111111-1111-1111-1111-111111111111",
"data": {
"video": { "id": "00000000-0000-4000-8000-00000000aa01" },
"referrer": "https://unauthorized.example/player"
}
}| Path | Type | Description |
|---|---|---|
data.video.id | string | UUID of the video whose embed was blocked. |
data.referrer | string | Effective referrer used in the check. May be an empty string if the request carried no Referer header. |
embed.token.invalid
When it fires. POST /telemetry/v1/token/refresh rejected the refresh token. The event
is emitted only when the playback session can still be resolved; requests where the session
itself is unknown are silently dropped.
{
"id": "evt_c3d4e5f6-a7b8-4901-c234-567890abcdef",
"type": "embed.token.invalid",
"created_at": "2026-05-09T23:05:00.000Z",
"organization_id": "11111111-1111-1111-1111-111111111111",
"data": {
"video": { "id": "00000000-0000-4000-8000-00000000aa01" },
"session": { "id": "33333333-3333-4333-8333-333333333333" },
"reason": "expired"
}
}| Path | Type | Description |
|---|---|---|
data.video.id | string | Video UUID resolved from the session row. |
data.session.id | string | Playback session UUID. |
data.reason | string | Validation failure key. Common values: expired, session_mismatch, unknown. |
usage.storage.threshold
When it fires. The usage evaluator detects that storage crossed 80%, 95%, or 100% of the plan allowance for the current billing period, and no notification was already recorded for that threshold in the period.
{
"id": "evt_d4e5f6a7-b8c9-4012-d345-678901bcdef0",
"type": "usage.storage.threshold",
"created_at": "2026-05-09T23:10:00.000Z",
"organization_id": "11111111-1111-1111-1111-111111111111",
"data": {
"threshold_percent": 80,
"used_bytes": 8589934592,
"limit_bytes": 10737418240,
"resource_type": "storage"
}
}| Path | Type | Description |
|---|---|---|
data.threshold_percent | number | Threshold crossed: 80, 95, or 100. |
data.used_bytes | number | Bytes currently used. |
data.limit_bytes | number | Plan allowance in bytes. |
data.resource_type | string | Always storage. |
usage.bandwidth.threshold
When it fires. Same evaluator logic as usage.storage.threshold, applied to
bandwidth consumed in the current billing period.
{
"id": "evt_e5f6a7b8-c9d0-4123-e456-789012345678",
"type": "usage.bandwidth.threshold",
"created_at": "2026-05-09T23:11:00.000Z",
"organization_id": "11111111-1111-1111-1111-111111111111",
"data": {
"threshold_percent": 95,
"used_bytes": 95000000000,
"limit_bytes": 100000000000,
"resource_type": "bandwidth"
}
}| Path | Type | Description |
|---|---|---|
data.threshold_percent | number | Threshold crossed: 80, 95, or 100. |
data.used_bytes | number | Bytes of bandwidth used in the billing period. |
data.limit_bytes | number | Plan allowance in bytes. |
data.resource_type | string | Always bandwidth. |