Embed & Usage Events

These events cover two areas: embed security (blocked referrers and rejected playback 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. A playback token refresh is rejected for a known viewer session. Invalid requests that cannot be associated with a viewer session are ignored.

{
  "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 for the viewer session.
`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`.