Koei's Digital Garden

Webhooks and Events

4 min read

Webhooks and Events

参照元: LiveKit Agents Documentation ロードマップ: 学習ロードマップ

一言まとめ

SDK Events = 状態変化の通知（何かが変わったことを知る） Track Stream = ストリーミング情報のリアルタイム描画・対応（実際のメディアデータを受け取る） Webhook = バックエンドへのサーバーサイド通知

Webhook vs SDK Events

WebhookSDK Events
向きLiveKit → バックエンド（HTTP POST）LiveKit SDK → アプリ・エージェント内
用途ビジネスロジック・ログ・外部システム連携リアルタイム UI 更新・エージェントの反応
具体例セッション開始をDBに記録、課金トリガーマイクアイコンの切り替え、エージェントの挨拶
graph LR
    LK["LiveKit Server"]

    LK -->|"HTTP POST\n（Webhook）"| B["🖥️ バックエンド"]
    LK -->|"SDK Events\n（コールバック）"| A["📱 アプリ / 🤖 エージェント"]

    B --- B_ex["• DB にセッション記録\n• 課金トリガー\n• 外部システム連携"]
    A --- A_ex["• UI 更新（マイクアイコン等）\n• エージェントの挨拶・反応\n• リアルタイム応答"]

エージェント開発では SDK Events を大量に使う。

SDK Events + Track Stream の使い分け

LiveKit フロントエンドのインタラクティブな表示はこの2層で動く：

graph TB
    SE["🔔 SDK Event\n（状態変化を知る）"]
    TS["📡 Track Stream\n（メディアデータを受け取る）"]

    SE -->|"「誰かが喋り始めた」\n「カメラが ON になった」"| UI["🖥️ UI 更新 / エージェント応答"]
    TS -->|"音声・映像・データ\nのリアルタイムストリーム"| UI

    SE_ex["例: ActiveSpeakersChanged\nTrackPublished / TrackUnpublished"] -.-> SE
    TS_ex["例: audio level データ\nvideo frame"] -.-> TS

具体例：音波形アニメーション

  • SDK Event ActiveSpeakersChanged で「Aさんが喋っている」を検知
  • Audio Track の audio level データをリアルタイムで読んで波形を描画

具体例：顔映像の表示

  • SDK Event TrackPublished で「Bさんのカメラが ON になった」を検知
  • Video Track のフレームをそのままレンダリング

接続の2フェーズ

Participant が Room に join するとき、接続は2段階：

  1. Signal connection — シグナリングチャネル確立（メタデータ・制御メッセージ）
  2. Media connection — 実際のメディア転送チャネル確立
sequenceDiagram
    participant C as Client / Agent
    participant L as LiveKit Server
    participant B as Backend

    C->>L: join()
    L-->>C: ✅ Signal connection 確立
    Note over C,L: Phase 1: シグナリング（制御・メタデータ）
    L-->>C: ✅ Media connection 確立
    Note over C,L: Phase 2: メディア転送（state = active）
    L->>B: participant_joined Webhook 🔔

    Note over C,L: ⚠️ Media が失敗した場合
    L--xC: Media connection 失敗
    L->>B: participant_connection_aborted Webhook ❌

Signal だけ繋がっても Media が失敗するケースがある（participant_connection_aborted）。 participant_joined Webhook は **Media connection 確立後（state = active）**に発火する。

Webhook Events 一覧

イベントタイミング
room_started最初の Participant が join して Room が始まったとき
room_finished最後の退出 → empty timeout 経過 → Room クローズ
participant_joinedMedia connection 確立後（state = active）
participant_left退出 & 全クリーンアップ完了後
participant_connection_abortedSignal は繋がったが Media が失敗したとき
track_publishedTrack が publish されたとき（payload の room/participant は SID・name・identity のみ）
track_unpublishedTrack が unpublish されたとき
egress_started録画・配信（Egress）開始
egress_updatedEgress 状態更新（例: 録画ファイルサイズ変化）
egress_endedEgress 終了
ingress_started外部メディア取り込み（Ingress）開始
ingress_endedIngress 終了

SDK Events の種類

Room events と Participant events の2種類。 Room events は Participant events のスーパーセット（Room 全体＋個別 Participant 両方受け取れる）。

→ UI コンポーネントを「この Participant だけ監視」する粒度で設計できる。

Webhook の信頼性

  • HTTP POST で配信。配信保証はない（best-effort）
  • 失敗時はリトライあり。複数イベントが溜まった場合は順序を保ってから届ける
  • Authorization ヘッダーに署名済み JWT が含まれる（正規 LiveKit からのリクエストか検証可能）

Graph View

Backlinks