コンテンツにスキップ
Documentation

RTC Webhook

RTCは、ルーム、参加者、録画、およびアカウントに関するイベントを Webhookに送信します エンドポイント 登録します。各エンドポイントには、独自のURL、イベント フィルター、署名用シークレット、および配信ログがあります。配信は 少なくとも1回: イベントの重複排除 id 実行する前に結果を報告します。

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.

Terminal window
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/endpointswebhooks:readエンドポイント(新しい順)(?projectId, ?limit, ?cursor)
POST /v1/webhooks/endpointswebhooks:write201、エンドポイントとその署名用シークレット(1回のみ表示)
GET /v1/webhooks/endpoints/{endpointId}webhooks:read1つのエンドポイント、以下を含む 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-secretwebhooks:write新しいシークレット(1回のみ表示)(ローテーション)
POST /v1/webhooks/endpoints/{endpointId}/testwebhooks:write送信 webhook.test 今すぐ実行し、結果を報告します
POST /v1/webhooks/endpoints/{endpointId}/replaywebhooks:write202、時間範囲による一括再生
GET /v1/webhooks/deliverieswebhooks:read配信ログ
GET /v1/webhooks/deliveries/{deliveryId}webhooks:read1回の配信につき、すべてのシークレットで試行
POST /v1/webhooks/deliveries/{deliveryId}/replaywebhooks:write202、その配信を再度送信します
GET /v1/webhooks/event-typeswebhooks: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 ルーティングは引き続き機能します。

新しいエンドポイントのシークレットは、以下の形式になります whsec_ その後にbase64が続きます。以下のように表示されます 一度、作成またはローテーションのリクエストに対するレスポンスに含まれ、RTCはこれを 暗号化して保存します。受信者のシークレットマネージャーに保存してください。サポートCHAMPREPを含め、 誰もそれを再度表示することはできません。紛失した場合は、シークレットをローテーションしてください。

署名用シークレットをチャット、チケット、またはログに貼り付けないでください。CHAMPREP AI アシスタントはエンドポイントの一覧表示、作成、テスト、再生を代行できますが、シークレットを 閲覧したり表示したりすることは決してありません。シークレットはコンソールから取得してください(Webhooks、その後 シークレットのローテーション).

ダウンタイムなしでシークレットをローテーションする

Section titled “ダウンタイムなしでシークレットをローテーションする”

POST /v1/webhooks/endpoints/{endpointId}/rotate-secret with { "overlapHours": 24 } 新しいシークレットを作成し、移行期間中は以前のシークレットも有効なまま に保ちます(0~72時間、デフォルトは24時間)。移行期間中、 すべての 配信は、有効なすべてのシークレットで署名されます、これにより受信者は 自分のペースで切り替えることができます:

  1. シークレットをローテーションし、新しいシークレットを受信側で古いシークレットの隣に保存してください。
  2. どちらのシークレットも受け入れるレシーバーをデプロイしてください。
  3. すべてのインスタンスが新しいシークレットを使用するようになったら、古いシークレットを削除してください。重複期間が終了すると、 署名処理は停止します(previousSecretsExpireAt).

使用方法 overlapHours: 0 まだ受信者がそのエンドポイントを使用していない場合、例えば、 AIアシスタントによって作成されたエンドポイントのシークレットを取得するためなどです。

新しいエンドポイントは バージョ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 は、ルームイベントに対して存在します。

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: 1794139200
X-RTC-Signature: v1=<hex>
X-RTC-Signatures: v1=<hex> v1=<hex>
webhook-id: 0b7c1a52-3d4e-4f5a-9b8c-7d6e5f4a3b2c
webhook-timestamp: 1794139200
webhook-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 エンコードが続きます。

この 検証例 は、依存関係なしに 両方のスキームを実装しています:

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 event
const event = JSON.parse(rawBody.toString('utf8'));
// Validate the envelope, then atomically deduplicate event.id in durable storage.

ローテーション中は、保有しているシークレットごとに1回ずつ検証プログラムを呼び出してください。

import base64
import hashlib
import hmac
import re
import 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を処理し、エンベロープを検証してください。

を返します。 2xx 検証済みのイベントを永続的に受け入れた後は速やかに応答し、 それ以上の処理は非同期で行ってください。各試行は5秒後にタイムアウトします。それ以外の ステータス、リダイレクト、またはタイムアウトは、試行の失敗とみなされます。

永続化 event.id アトミックに処理し、各イベントを一度だけ処理してください。メモリ内のセットだけでは、 再起動時や複数の受信インスタンス間では不十分です。タイムスタンプのチェック だけでは、許容ウィンドウ内でのリプレイを防ぐことはできません。順序は 保証されません。タイムスタンプを data および を使用して、現在の状態を解決してくださいAPI。

配信に失敗した場合は、指数関数的なバックオフとジッターを適用して約 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 }.

  • テストイベントを送信し、その status および error.
  • 配信ログの lastStatus および試行時のレスポンスの抜粋。
  • スキーマに応じた正しいキーを使用して、生のバイトを検証していることを確認してください (デコードされた whsec_ Standard Webhooksの場合はその部分、の場合は文字列全体を X-RTC-Signature).
  • クロックのずれ、リダイレクト、およびエンドポイントが有効になっていることを確認してください。

トラブルシューティング中は、署名用シークレット、署名を含む生のリクエスト、または参加者の 認証情報を決してログに記録しないでください。