RTC Webhook
RTCは、ルーム、参加者、録画、およびアカウントに関するイベントを Webhookに送信します エンドポイント 登録します。各エンドポイントには、独自のURL、イベント フィルター、署名用シークレット、および配信ログがあります。配信は 少なくとも1回: イベントの重複排除 id 実行する前に結果を報告します。
エンドポイント
Section titled “エンドポイント”RTCコンソールの以下の項目でエンドポイントを管理します Webhook、 を通じてAPI、 コンソールセッションAPI、または webhooks:read
または webhooks:write スコープ。プロジェクトキーは、 自身のプロジェクトのエンドポイントのみを表示・管理します。
| 設定 | 意味 |
|---|---|
| URL | ポート443上の公開HTTPS URLです。リダイレクトは追跡されず、プライベートアドレスや予約済みアドレスは拒否されます。これは保存時およびすべての試行時に適用されます。 |
| プロジェクト | 1つのプロジェクト、または組織内のすべてのプロジェクト(projectId: null). |
| イベント | フィルター: * すべてのイベントについて、次のようなファミリーが recording.*、または次のような1つのタイプなど room.ended。既知のタイプに一致しないフィルターは拒否されます。 |
| 有効 | 無効化されたエンドポイントには何も送信されません。RTCは、エンドポイントが繰り返し失敗した場合、自動的にそのエンドポイントを無効化します(詳細は 再試行と自動無効化). |
| 説明 | 独自のラベル(最大500文字)。 |
エンドポイントの数はご利用のプランによって異なります。プランの制限数より1つ多く作成すると、 回答が可能になります 409 コードとともに
WEBHOOK_ENDPOINT_LIMIT.
curl --fail-with-body https://api.rtc.champrep.com/v1/webhooks/endpoints \ --header "Authorization: Bearer $RTC_API_KEY" \ --header "Content-Type: application/json" \ --data '{ "url": "https://hooks.example.com/rtc", "description": "Production receiver", "events": ["room.*", "recording.ready"] }'| メソッドとパス | スコープ | 結果 |
|---|---|---|
GET /v1/webhooks/endpoints | webhooks:read | エンドポイント(新しい順)(?projectId, ?limit, ?cursor) |
POST /v1/webhooks/endpoints | webhooks:write | 201、エンドポイントとその署名用シークレット(1回のみ表示) |
GET /v1/webhooks/endpoints/{endpointId} | webhooks:read | 1つのエンドポイント、以下を含む limit: { used, limit } |
PATCH /v1/webhooks/endpoints/{endpointId} | webhooks:write | 変更 url, description, events または enabled |
DELETE /v1/webhooks/endpoints/{endpointId} | webhooks:write | { "deleted": true } |
POST /v1/webhooks/endpoints/{endpointId}/rotate-secret | webhooks:write | 新しいシークレット(1回のみ表示)(ローテーション) |
POST /v1/webhooks/endpoints/{endpointId}/test | webhooks:write | 送信 webhook.test 今すぐ実行し、結果を報告します |
POST /v1/webhooks/endpoints/{endpointId}/replay | webhooks:write | 202、時間範囲による一括再生 |
GET /v1/webhooks/deliveries | webhooks:read | 配信ログ |
GET /v1/webhooks/deliveries/{deliveryId} | webhooks:read | 1回の配信につき、すべてのシークレットで試行 |
POST /v1/webhooks/deliveries/{deliveryId}/replay | webhooks:write | 202、その配信を再度送信します |
GET /v1/webhooks/event-types | webhooks:read | イベントカタログ |
エンドポイントオブジェクトには、シークレット値は一切含まれません。各有効なシークレットの
id、その概要は prefix (例: whsec_Ab12), createdAt また、 ローテーション中は、 expiresAt。また、以下のレポートも提供されます status (active または disabled),
disabledReason (manual, failing, gone または admin)および health
(consecutiveFailures, lastSuccessAt, lastFailureAt, failingSince).
エンドポイントのサポートCHAMPREPがオフになっている場合(disabledReason: "admin") は 有効化したり、テストイベントを送信したりすることはできません (WEBHOOK_ENDPOINT_ADMIN_DISABLED)、 そのURLを新しいエンドポイントとして再度追加することはできません (WEBHOOK_URL_ADMIN_DISABLED)。 サポートまでお問い合わせください。
一覧表示ではJSON配列が返されます。項目が複数存在する場合、 X-Next-Cursor レスポンス ヘッダーには次のページへのカーソル情報が含まれています。これを ?cursor.
?limit 1~200まで指定可能です。
以前の単一Webhookを設定していたワークスペース(PUT /v1/webhook) 保持 :これによって、すべてのプロジェクトおよびすべてのイベントに対してエンドポイントとして表示され、マークされます
legacy: true、そして /v1/webhook ルーティングは引き続き機能します。
シークレットの署名
Section titled “シークレットの署名”新しいエンドポイントのシークレットは、以下の形式になります whsec_ その後にbase64が続きます。以下のように表示されます
一度、作成またはローテーションのリクエストに対するレスポンスに含まれ、RTCはこれを 暗号化して保存します。受信者のシークレットマネージャーに保存してください。サポートCHAMPREPを含め、 誰もそれを再度表示することはできません。紛失した場合は、シークレットをローテーションしてください。
署名用シークレットをチャット、チケット、またはログに貼り付けないでください。CHAMPREP AI アシスタントはエンドポイントの一覧表示、作成、テスト、再生を代行できますが、シークレットを 閲覧したり表示したりすることは決してありません。シークレットはコンソールから取得してください(Webhooks、その後 シークレットのローテーション).
ダウンタイムなしでシークレットをローテーションする
Section titled “ダウンタイムなしでシークレットをローテーションする”POST /v1/webhooks/endpoints/{endpointId}/rotate-secret with
{ "overlapHours": 24 } 新しいシークレットを作成し、移行期間中は以前のシークレットも有効なまま に保ちます(0~72時間、デフォルトは24時間)。移行期間中、 すべての 配信は、有効なすべてのシークレットで署名されます、これにより受信者は 自分のペースで切り替えることができます:
- シークレットをローテーションし、新しいシークレットを受信側で古いシークレットの隣に保存してください。
- どちらのシークレットも受け入れるレシーバーをデプロイしてください。
- すべてのインスタンスが新しいシークレットを使用するようになったら、古いシークレットを削除してください。重複期間が終了すると、 署名処理は停止します(
previousSecretsExpireAt).
使用方法 overlapHours: 0 まだ受信者がそのエンドポイントを使用していない場合、例えば、 AIアシスタントによって作成されたエンドポイントのシークレットを取得するためなどです。
イベント・エンベロープ
Section titled “イベント・エンベロープ”新しいエンドポイントは バージョAPIンを使用します 2026-11-01:
{ "id": "0b7c1a52-3d4e-4f5a-9b8c-7d6e5f4a3b2c", "type": "room.ended", "apiVersion": "2026-11-01", "createdAt": "2026-11-08T12:00:00.000Z", "tenantId": "00000000-0000-4000-8000-000000000009", "projectId": "00000000-0000-4000-8000-000000000001", "roomId": "00000000-0000-4000-8000-000000000003", "data": { "roomId": "00000000-0000-4000-8000-000000000003", "endedAt": "2026-11-08T12:00:00.000Z" }}レガシーエンドポイントは以前のエンベロープを保持し、
{ id, type, createdAt, projectId, data }。エンドポイントの apiVersion 受信したペイロードの形状を 固定します。詳細は バージョン管理.
上記のIDはあくまで例です。扱いは id 不透明な文字列として:UUIDであるものもあれば、 以下のように派生したものであるものもあります: recording-ready:<uuid>. projectId 存在しない場合があります 組織レベルのイベントの場合、および roomId は、ルームイベントに対して存在します。
イベントカタログ
Section titled “イベントカタログ”GET /v1/webhooks/event-types 権威あるリストを返します。各タイプには 説明と status: live (送信)または planned (すでに購読している可能性のある 予約済み名です。現時点では何も送信されていません)。一部のライブイベントは、 お使いのワークスペースで関連する機能が有効になっている場合にのみ送信されます。
| イベント | ステータス | 送信タイミング |
|---|---|---|
room.created | 有効 | ルームが作成されました |
room.started | 有効 | 最初の参加者がルームに参加しました |
room.empty | 有効 | 最後の参加者がオープンルームを退出しました |
room.idle_timeout | 有効 | オープンルームに、アイドル期間中( , )の間、参加者がいませんでしたdata.idleSince, data.idleMinutes) |
room.locked | 有効 | ルームがロックまたはロック解除されました |
room.ended | 有効 | ルームが終了しました |
participant.joined | 有効 | 参加者がルームに参加しました |
participant.left | 有効 | 参加者がルームを退出しました |
participant.updated | 有効 | モデレーターが参加者の設定を変更しました(役割、権限、名前、メタデータ、ホストによるミュート) |
participant.connection_quality | 計画中 | 接続品質のサンプリング(オプトイン) |
track.published | 有効 | 参加者がトラックを公開しました |
track.unpublished | 有効 | 参加者がトラックを停止しました |
track.muted | 有効 | 参加者がトラックをミュートしたか、ホストがミュートしました |
track.unmuted | 有効 | ミュートされていたトラックのミュートが解除されました |
recording.requested | 有効 | 録画の再生がリクエストされました |
recording.started | 有効 | 録画のキャプチャが開始されました |
recording.stopped | 有効 | 録画が停止しました(1つの録画につき1回のみ)。 reason (requested, room_ended, max_duration, limit, tenant_inactive, shutdown, allowance 録画の保存時間が使い切られた場合、 billing_unavailable または error) |
recording.ready | 有効 | 録画のすべてのトラックが保存されています |
recording.failed | 有効 | 録画の終了に失敗しました(キャプチャされたトラックは保持される場合があります) |
recording.composite.ready | 有効 | コンポジットビデオおよびオーディオファイルが保存されています |
recording.composite.failed | 有効 | 合成ファイルを作成できませんでした |
recording.delivered | 有効 | 録画ファイルがご自身のストレージに配信されました |
recording.delivery_failed | 有効 | 録画ファイルを自身のストレージに配信できませんでした |
recording.deleted | 有効 | 録画がゴミ箱に移動されました: data です { recordingId, roomId, reason, deletedAt, purgeAt }、以下のいずれかの理由で reason customer (ご自身で削除された場合)または retention (保存期間が終了したため)、および purgeAt 自動削除された場合(30日後;ゴミ箱に送られた時点で確定し、 null ゴミ箱の自動削除がオフになっている場合)。それまでは復元可能です。 |
recording.restored | 有効 | 録画がゴミ箱から復元されました: data です { recordingId, roomId, restoredAt, by }、以下のいずれかの理由で by customer または admin |
recording.purged | 有効 | 録画がゴミ箱から完全に削除されました: data です { recordingId, roomId, reason, purgedAt }、 reason customer (ごみ箱から削除された場合)、 expired (30日後に自動削除されます)または admin (CHAMPREPサポート) |
transcript.queued | 有効 | 録画の文字起こしで所要時間が確保され、キューに入れられました: data です { recordingId, roomId, reservedMinutes } (文字起こし) |
transcript.completed | 有効 | 録画の文字起こしが完了しました: data です { recordingId, roomId, segments, durationMs, billedMinutes, truncated }、 truncated true クロストークが激しい際に割り当てが枯渇した場合。テキストは一切表示されません。 |
transcript.failed | 有効 | 録画の文字起こしに失敗し、課金されませんでした: data です { recordingId, roomId, error }、さらに code (RTC_ALLOWANCE_EXHAUSTED, BILLING_UNAVAILABLE, CANCELLED または RECORDING_LENGTH_UNKNOWN)および offers 割り当てが理由である場合 |
transcript.segment | 計画中 | お客様にはまだご利用いただけません(ライブキャプション) |
captions.started | 計画中 | お客様にはまだご利用いただけません |
captions.stopped | 計画中 | お客様にはまだご利用いただけません |
whiteboard.created | 有効 | ルーム内にホワイトボードが作成されました |
whiteboard.archived | 有効 | ホワイトボードがアーカイブまたは削除されました |
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.ready | 計画中 | ホワイトボードのアクティビティ |
key.created | 有効 | キーAPIが作成されました |
key.revoked | 有効 | キーAPIが無効化されました |
quota.warning | 有効 | RTC 割り当てが警告パーセンテージ(CHAMPREP で他の値が設定CHAMPREPされていない限り 80%)を超えました。割り当て、請求期間、およびパーセンテージごとに 1 回 |
quota.exhausted | 有効 | RTCの割り当てが消費されます(サブスクリプション、トライアル、パック)。割り当ておよび請求期間ごとに1回 |
subscription.changed | 計画中 | RTCのサブスクリプションに変更がありました(プラン、トライアル、支払いに関する問題) |
webhook.test | 有効 | コンソールまたは API |
webhook.endpoint_disabled | 有効 | エンドポイントの1つが、失敗または応答した後に無効化されました 410: data は { endpointId, url, host, reason }. url はスキーム、ホスト、パスのみであり、クエリ文字列は含まれません; host はホスト名のみです; reason は failing または gone. |
egress.started, egress.ended, ingress.started, ingress.ended | 計画中 | ストリーミングおよびインジェスト(まだ利用不可) |
イベントには識別子が含まれますが、表示名、トークン、IPアドレス、メディアは含まれません。 1つのイベントに依存するのではなくAPI、重要な状態を と照合してください。
すべてのリクエストを検証する
Section titled “すべてのリクエストを検証する”各配信には、2つの独立した署名方式が含まれています。検証してください 1つ それらを、 リクエスト本文のバイト列をそのまま正確に、JSONの解析や処理を行う前に。 検証のためにボディを解析して再シリアライズすることは絶対に避けてください。
X-RTC-Timestamp: 1794139200X-RTC-Signature: v1=<hex>X-RTC-Signatures: v1=<hex> v1=<hex>webhook-id: 0b7c1a52-3d4e-4f5a-9b8c-7d6e5f4a3b2cwebhook-timestamp: 1794139200webhook-signature: v1,<base64> v1,<base64>| スキーム | 署名付きコンテンツ | HMAC-SHA256 キー | 署名 |
|---|---|---|---|
| 標準 Webhook (推奨) | <webhook-id>.<webhook-timestamp>.<raw body> | whsec_… secrets: プレフィックスの後のBase64デコード済み部分 whsec_ プレフィックス。移行されたレガシー rtc_… シークレット:シークレット全体のUTF-8バイトデータ | webhook-signature: スペース区切り v1,<base64>、有効なシークレットごとに1つずつ |
| RTC(レガシー) | <X-RTC-Timestamp>.<raw body> | 「」を含む、シークレット文字列全体のUTF-8バイト: 最新のシークレット用; : 有効なすべてのシークレット(スペース区切り) whsec_ または rtc_ プレフィックス | X-RTC-Signature: v1=<hex> 最新のシークレット用; X-RTC-Signatures: すべての有効なシークレット(スペース区切り) |
両方のスキームにおいて:
- ご自身の時計から5分以上ずれているタイムスタンプは拒否してください。
- 定数時間で署名を比較し、以下の条件を満たす場合はリクエストを受け入れます。 任意 リストされた署名が、ご自身のシークレットのいずれかと一致する場合。
- 処理中に ローテーションの重複,
X-RTC-Signatureには最新のシークレットのみが含まれます。以前のシークレットを まだ保持しているレガシー受信機は、以下を確認する必要がありますX-RTC-Signatures. - 既製の標準Webhooksライブラリは、
whsec_シークレットを直接。 移行済みのrtc_…シークレットについては、ライブラリにwhsec_その後に、 シークレット全体の UTF-8 バイト列の base64 エンコードが続きます。
Node.js
Section titled “Node.js”この 検証例 は、依存関係なしに 両方のスキームを実装しています:
import { verifyStandardWebhook, verifyRtcWebhook } from './verify-webhook.mjs';
// rawBody: the Buffer captured before any JSON middleware.const valid = verifyStandardWebhook({ rawBody, id: request.headers['webhook-id'], timestamp: request.headers['webhook-timestamp'], signature: request.headers['webhook-signature'], secret: process.env.RTC_WEBHOOK_SECRET,}) || verifyRtcWebhook({ rawBody, timestamp: request.headers['x-rtc-timestamp'], signatures: request.headers['x-rtc-signatures'], signature: request.headers['x-rtc-signature'], secret: process.env.RTC_WEBHOOK_SECRET,});if (!valid) return rejectWebhook(); // 401, without applying the eventconst event = JSON.parse(rawBody.toString('utf8'));// Validate the envelope, then atomically deduplicate event.id in durable storage.ローテーション中は、保有しているシークレットごとに1回ずつ検証プログラムを呼び出してください。
Python
Section titled “Python”import base64import hashlibimport hmacimport reimport time
TOLERANCE_SECONDS = 300
def _fresh(timestamp, now=None): if not timestamp or not re.fullmatch(r"[0-9]{1,12}", timestamp): return False return abs((now or time.time()) - int(timestamp)) <= TOLERANCE_SECONDS
def _any_match(expected, header, prefix): entries = header.split(" ") if header else [] matched = False for entry in entries[:16]: if entry.startswith(prefix) and hmac.compare_digest(entry[len(prefix):], expected): matched = True return matched
def standard_webhook_key(secret): """whsec_ secrets: the base64 part after the prefix. Legacy rtc_ secrets: the whole secret.""" if secret.startswith("whsec_"): return base64.b64decode(secret[len("whsec_"):], validate=True) return secret.encode("utf-8")
def verify_standard_webhook(raw_body: bytes, headers, secret: str) -> bool: msg_id = headers.get("webhook-id") timestamp = headers.get("webhook-timestamp") if not msg_id or not _fresh(timestamp): return False signed = f"{msg_id}.{timestamp}.".encode() + raw_body digest = hmac.new(standard_webhook_key(secret), signed, hashlib.sha256).digest() return _any_match(base64.b64encode(digest).decode(), headers.get("webhook-signature"), "v1,")
def verify_rtc_webhook(raw_body: bytes, headers, secret: str) -> bool: timestamp = headers.get("x-rtc-timestamp") if not _fresh(timestamp): return False signed = timestamp.encode() + b"." + raw_body digest = hmac.new(secret.encode("utf-8"), signed, hashlib.sha256).hexdigest() header = headers.get("x-rtc-signatures") or headers.get("x-rtc-signature") return _any_match(digest, header, "v1=")headers は、大文字小文字を区別しないマッピングである必要があります。例えば、 request.headers Flask、Django、またはStarletteで、 そして raw_body 解析されていない本文 (request.get_data() Flask では、 request.body Django では、 await request.body()
(Starlette内)。
これらの例は、レシーバー統合のガイダンスであり、完全なサーバーではありません。 リクエストボディの制限を設定し、不正な形式のJSONを処理し、エンベロープを検証してください。
応答、重複排除、順序付け
Section titled “応答、重複排除、順序付け”を返します。 2xx 検証済みのイベントを永続的に受け入れた後は速やかに応答し、 それ以上の処理は非同期で行ってください。各試行は5秒後にタイムアウトします。それ以外の ステータス、リダイレクト、またはタイムアウトは、試行の失敗とみなされます。
永続化 event.id アトミックに処理し、各イベントを一度だけ処理してください。メモリ内のセットだけでは、 再起動時や複数の受信インスタンス間では不十分です。タイムスタンプのチェック だけでは、許容ウィンドウ内でのリプレイを防ぐことはできません。順序は 保証されません。タイムスタンプを data および を使用して、現在の状態を解決してくださいAPI。
再試行と自動無効化
Section titled “再試行と自動無効化”配信に失敗した場合は、指数関数的なバックオフとジッターを適用して約 24時間(12回の試行)再試行され、その後、 dead. すべての試行は、 エンドポイントの有効なシークレットと新しいタイムスタンプを用いて、その都度新たに署名されます。
各試行は5秒後にタイムアウトします。RTCは、以下のいずれかの条件が満たされた場合、 エンドポイントを無効化します (disabledReason: "failing") 以下のいずれかの条件が満たされた場合:
- 25回連続でタイムアウトが発生し、かつ 少なくとも1時間にわたり失敗が続いている場合;
- 24時間連続で失敗し続けている場合(CHAMPREP別の 期間を設定することも可能です)。
応答があった場合、エンドポイントは直ちに無効化されます("gone")が応答した際 410 Gone。 組織の所有者に通知され、 webhook.endpoint_disabled イベントは 他のエンドポイントに送信されます。受信側を修正した後、エンドポイントを再度有効にしてください (PATCH で { "enabled": true });を有効にすると、その失敗状態がクリアされます。
テスト、配信ログ、および再生
Section titled “テスト、配信ログ、および再生”- テスト:
POST /v1/webhooks/endpoints/{endpointId}/testはwebhook.testイベントを直ちに処理し、応答が返されます。{ deliveryId, eventId, ok, status, latencyMs, error }. - 配信ログ:
GET /v1/webhooks/deliveries配信を一覧表示します。最新のものが 最初に表示され、state(pending,retry,delivered,dead,cancelled),attempts,lastStatus,lastErrorおよびlastLatencyMs。でフィルタリングします。?endpointId,?state,?typeおよび?eventId。1回の配信 (GET /v1/webhooks/deliveries/{deliveryId}) には、各試行の ステータス、レイテンシ、受信者の応答の最初の 1 KB、および イベント自体が追加されます。ログは一定期間保存されます。 - リプレイ1:
POST /v1/webhooks/deliveries/{deliveryId}/replayキューに 配信を再度追加します。配信ごとおよび1日あたりのリプレイ回数には制限があります (REPLAY_LIMIT,REPLAY_QUOTA); 配信が行われていると、応答が返されます。DELIVERY_IN_PROGRESS. - 一括再生:
POST /v1/webhooks/endpoints/{endpointId}/replayで{ "from": "2026-11-08T00:00:00Z", "to": "2026-11-08T06:00:00Z", "types": ["recording.*"], "onlyFailed": true }そのエンドポイントの指定された時間範囲に一致するイベントをキューに格納し(リクエストあたり最大 1000件)、応答が返されます。202 { "queued": n }.
トラブルシューティング
Section titled “トラブルシューティング”- テストイベントを送信し、その
statusおよびerror. - 配信ログの
lastStatusおよび試行時のレスポンスの抜粋。 - スキーマに応じた正しいキーを使用して、生のバイトを検証していることを確認してください (デコードされた
whsec_Standard Webhooksの場合はその部分、の場合は文字列全体をX-RTC-Signature). - クロックのずれ、リダイレクト、およびエンドポイントが有効になっていることを確認してください。
トラブルシューティング中は、署名用シークレット、署名を含む生のリクエスト、または参加者の 認証情報を決してログに記録しないでください。