Skip to content
Documentation

RTC webhooks

RTC sends events about your rooms, participants, recordings and account to webhook endpoints you register. Each endpoint has its own URL, event filters, signing secrets and delivery log. Delivery is at least once: deduplicate on the event id before acting.

Manage endpoints in the RTC console under Webhooks, through the API with your console session, or with a project API key that has the webhooks:read or webhooks:write scope. A project key only sees and manages the endpoints of its own project.

SettingMeaning
URLA public HTTPS URL on port 443. Redirects are not followed and private or reserved addresses are refused, both when you save and on every attempt.
ProjectOne project, or all projects of the organization (projectId: null).
EventsFilters: * for every event, a family such as recording.*, or one type such as room.ended. A filter that matches no known type is refused.
EnabledDisabled endpoints receive nothing. RTC disables an endpoint itself when it keeps failing (see Retries and automatic disable).
DescriptionYour own label, up to 500 characters.

The number of endpoints depends on your plan. Creating one more than the plan allows answers 409 with the code 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"] }'
Method and pathScopeResult
GET /v1/webhooks/endpointswebhooks:readEndpoints, newest first (?projectId, ?limit, ?cursor)
POST /v1/webhooks/endpointswebhooks:write201, the endpoint and its signing secret, shown once
GET /v1/webhooks/endpoints/{endpointId}webhooks:readOne endpoint, with limit: { used, limit }
PATCH /v1/webhooks/endpoints/{endpointId}webhooks:writeChange url, description, events or enabled
DELETE /v1/webhooks/endpoints/{endpointId}webhooks:write{ "deleted": true }
POST /v1/webhooks/endpoints/{endpointId}/rotate-secretwebhooks:writeA new secret, shown once (rotation)
POST /v1/webhooks/endpoints/{endpointId}/testwebhooks:writeSends webhook.test now and reports the result
POST /v1/webhooks/endpoints/{endpointId}/replaywebhooks:write202, bulk replay by time range
GET /v1/webhooks/deliverieswebhooks:readThe delivery log
GET /v1/webhooks/deliveries/{deliveryId}webhooks:readOne delivery, with every attempt
POST /v1/webhooks/deliveries/{deliveryId}/replaywebhooks:write202, sends that delivery again
GET /v1/webhooks/event-typeswebhooks:readThe event catalog

An endpoint object never contains a secret value. It lists each live secret’s id, its short prefix (for example whsec_Ab12), createdAt and, during a rotation, expiresAt. It also reports status (active or disabled), disabledReason (manual, failing, gone or admin) and health (consecutiveFailures, lastSuccessAt, lastFailureAt, failingSince).

An endpoint CHAMPREP support turned off (disabledReason: "admin") cannot be enabled or sent a test event (WEBHOOK_ENDPOINT_ADMIN_DISABLED), and its URL cannot be added again as a new endpoint (WEBHOOK_URL_ADMIN_DISABLED). Contact support.

Lists return a JSON array. When more items exist, the X-Next-Cursor response header carries the cursor for the next page; pass it back as ?cursor. ?limit accepts 1 to 200.

Workspaces that configured the earlier single webhook (PUT /v1/webhook) keep it: it now appears as an endpoint for all projects and all events, marked legacy: true, and the /v1/webhook routes keep working.

A new endpoint’s secret has the form whsec_ followed by base64. It is shown once, in the response to the create or rotate request, and RTC stores it encrypted. Store it in your receiver’s secret manager; nobody can show it to you again, including CHAMPREP support. If you lose it, rotate the secret.

Never paste a signing secret into a chat, ticket or log. The CHAMPREP AI assistant can list, create, test and replay endpoints for you, but it never sees or shows a secret: get one in the console (Webhooks, then Rotate secret).

POST /v1/webhooks/endpoints/{endpointId}/rotate-secret with { "overlapHours": 24 } creates a new secret and keeps the previous ones valid for the overlap (0 to 72 hours, 24 by default). During the overlap every delivery is signed with every live secret, so receivers can switch at their own pace:

  1. Rotate and store the new secret next to the old one in your receiver.
  2. Deploy a receiver that accepts either secret.
  3. When every instance uses the new secret, remove the old one. It stops signing when the overlap ends (previousSecretsExpireAt).

Use overlapHours: 0 when no receiver uses the endpoint yet, for example to obtain a secret for an endpoint created by the AI assistant.

New endpoints use API version 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" }
}

The legacy endpoint keeps the earlier envelope, { id, type, createdAt, projectId, data }. An endpoint’s apiVersion pins the payload shape it receives; see versioning.

The IDs above are illustrative. Treat id as an opaque string: some are UUIDs, others are derived, such as recording-ready:<uuid>. projectId may be absent for an organization-level event, and roomId is present for room events.

GET /v1/webhooks/event-types returns the authoritative list, each type with a description and status: live (sent) or planned (a reserved name you may already subscribe to; nothing is sent yet). Some live events are only sent when the related feature is enabled for your workspace.

EventStatusSent when
room.createdliveA room was created
room.startedliveThe first participant joined a room
room.emptyliveThe last participant left an open room
room.idle_timeoutliveAn open room has had no participants for the idle period (data.idleSince, data.idleMinutes)
room.lockedliveA room was locked or unlocked
room.endedliveA room was ended
participant.joinedliveA participant joined a room
participant.leftliveA participant left a room
participant.updatedliveA moderator changed a participant (role, permissions, name, metadata, host mute)
participant.connection_qualityplannedSampled connection quality (opt-in)
track.publishedliveA participant published a track
track.unpublishedliveA participant stopped a track
track.mutedliveA participant muted a track, or a host muted it
track.unmutedliveA muted track was unmuted
recording.requestedliveA recording was requested
recording.startedliveCapture of a recording started
recording.stoppedliveCapture stopped, once per recording, with the reason (requested, room_ended, max_duration, limit, tenant_inactive, shutdown, allowance when the recording minutes are used up, billing_unavailable or error)
recording.readyliveEvery track of a recording is stored
recording.failedliveA recording ended failed (captured tracks may be kept)
recording.composite.readyliveThe composite video and audio files are stored
recording.composite.failedliveNo composite file could be made
recording.deliveredliveA recording file was delivered to your own storage
recording.delivery_failedliveA recording file could not be delivered to your own storage
recording.deletedliveA recording was sent to Trash: data is { recordingId, roomId, reason, deletedAt, purgeAt }, with reason customer (you deleted it) or retention (its retention ended), and purgeAt when it is auto-deleted (30 days later; fixed when it is sent to Trash, null while the Trash auto-delete is off). It can be restored until then.
recording.restoredliveA recording was restored from Trash: data is { recordingId, roomId, restoredAt, by }, with by customer or admin
recording.purgedliveA recording was deleted permanently from Trash: data is { recordingId, roomId, reason, purgedAt }, with reason customer (you deleted it from Trash), expired (auto-deleted after 30 days) or admin (CHAMPREP support)
transcript.queuedliveA recording’s transcript reserved its minutes and is queued: data is { recordingId, roomId, reservedMinutes } (transcription)
transcript.completedliveA recording’s transcript is ready: data is { recordingId, roomId, segments, durationMs, billedMinutes, truncated }, with truncated true when the allowance ran out during heavy crosstalk. Never the text.
transcript.failedliveA recording’s transcript failed and nothing was charged: data is { recordingId, roomId, error }, plus code (RTC_ALLOWANCE_EXHAUSTED, BILLING_UNAVAILABLE, CANCELLED or RECORDING_LENGTH_UNKNOWN) and offers when the allowance is the reason
transcript.segmentplannedNot yet available to customers (live captions)
captions.startedplannedNot yet available to customers
captions.stoppedplannedNot yet available to customers
whiteboard.createdliveA whiteboard was created in a room
whiteboard.archivedliveA whiteboard was archived or deleted
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.readyplannedWhiteboard activity
key.createdliveAn API key was created
key.revokedliveAn API key was revoked
quota.warningliveAn RTC allowance passed a warning percentage (80 % unless CHAMPREP sets others); once per allowance, billing period and percentage
quota.exhaustedliveAn RTC allowance is used up (subscription, trial and packs); once per allowance and billing period
subscription.changedplannedThe RTC subscription changed (tier, trial, payment problem)
webhook.testliveA test event sent from the console or the API
webhook.endpoint_disabledliveOne of your endpoints was disabled after failing or answering 410: data is { endpointId, url, host, reason }. url is the scheme, host and path only, never the query string; host is the host on its own; reason is failing or gone.
egress.started, egress.ended, ingress.started, ingress.endedplannedStreaming and ingest (not available yet)

Events carry identifiers, not display names, tokens, IP addresses or media. Reconcile important state with the API rather than depending on one event.

Each delivery carries two independent signature schemes. Verify one of them, over the exact raw request body bytes, before parsing JSON or acting. Never parse and re-serialize the body for verification.

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>
SchemeSigned contentHMAC-SHA256 keySignature
Standard Webhooks (recommended)<webhook-id>.<webhook-timestamp>.<raw body>whsec_… secrets: the base64-decoded part after the whsec_ prefix. Migrated legacy rtc_… secrets: the UTF-8 bytes of the whole secretwebhook-signature: space-separated v1,<base64>, one per live secret
RTC (legacy)<X-RTC-Timestamp>.<raw body>The UTF-8 bytes of the whole secret string, including any whsec_ or rtc_ prefixX-RTC-Signature: v1=<hex> for the newest secret; X-RTC-Signatures: every live secret, space-separated

For both schemes:

  • Reject a timestamp more than five minutes from your clock.
  • Compare signatures in constant time, and accept the request when any listed signature matches one of your secrets.
  • During a rotation overlap, X-RTC-Signature carries only the newest secret. A legacy receiver that still holds the previous secret must check X-RTC-Signatures.
  • Off-the-shelf Standard Webhooks libraries accept whsec_ secrets directly. For a migrated rtc_… secret, give the library whsec_ followed by the base64 encoding of the whole secret’s UTF-8 bytes.

The verification example implements both schemes without dependencies:

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.

During a rotation, call the verifier once per secret you hold.

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 must be a case-insensitive mapping, such as request.headers in Flask, Django or Starlette, and raw_body the unparsed body (request.get_data() in Flask, request.body in Django, await request.body() in Starlette).

These examples are receiver integration guidance, not complete servers. Set a request body limit, handle malformed JSON and validate the envelope.

Return a 2xx response promptly after durably accepting a verified event, and do longer work asynchronously. Each attempt times out after 5 seconds. Any other status, a redirect or a timeout counts as a failed attempt.

Persist event.id atomically and process each event once; an in-memory set is not enough across restarts or several receiver instances. The timestamp check alone does not prevent a replay within the accepted window. Ordering is not guaranteed: use timestamps in data and the API to resolve the current state.

A failed delivery is retried with exponential backoff and jitter for about 24 hours (12 attempts), then marked dead. Every attempt is signed afresh with the endpoint’s live secrets and a new timestamp.

Each attempt times out after 5 seconds. RTC disables an endpoint (disabledReason: "failing") when either of these holds:

  • it has timed out 25 times in a row, and it has also been failing for at least 1 hour;
  • it has been failing continuously for 24 hours (CHAMPREP may set another period).

It disables it at once ("gone") when it answers 410 Gone. The organization owner is notified, and a webhook.endpoint_disabled event is sent to your other endpoints. Fix the receiver, then enable the endpoint again (PATCH with { "enabled": true }); enabling clears its failure state.

  • Test: POST /v1/webhooks/endpoints/{endpointId}/test sends a webhook.test event right away and answers { deliveryId, eventId, ok, status, latencyMs, error }.
  • Delivery log: GET /v1/webhooks/deliveries lists deliveries, newest first, with state (pending, retry, delivered, dead, cancelled), attempts, lastStatus, lastError and lastLatencyMs. Filter with ?endpointId, ?state, ?type and ?eventId. One delivery (GET /v1/webhooks/deliveries/{deliveryId}) adds every attempt with its status, latency and the first 1 KB of your receiver’s response, and the event itself. The log is kept for a limited period.
  • Replay one: POST /v1/webhooks/deliveries/{deliveryId}/replay queues the delivery again. Replays per delivery and per day are limited (REPLAY_LIMIT, REPLAY_QUOTA); a delivery being sent answers DELIVERY_IN_PROGRESS.
  • Bulk replay: POST /v1/webhooks/endpoints/{endpointId}/replay with { "from": "2026-11-08T00:00:00Z", "to": "2026-11-08T06:00:00Z", "types": ["recording.*"], "onlyFailed": true } queues the matching events of that time range for the endpoint, at most 1000 per request, and answers 202 { "queued": n }.
  • Send a test event and read its status and error.
  • Read the delivery log’s lastStatus and the attempt’s response excerpt.
  • Check that you verify the raw bytes with the right key for the scheme (the decoded whsec_ part for Standard Webhooks, the whole string for X-RTC-Signature).
  • Check clock skew, redirects, and that the endpoint is enabled.

Never log the signing secret, signature-bearing raw requests or participant credentials while troubleshooting.