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.
Endpoints
Section titled “Endpoints”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.
| Setting | Meaning |
|---|---|
| URL | A 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. |
| Project | One project, or all projects of the organization (projectId: null). |
| Events | Filters: * for every event, a family such as recording.*, or one type such as room.ended. A filter that matches no known type is refused. |
| Enabled | Disabled endpoints receive nothing. RTC disables an endpoint itself when it keeps failing (see Retries and automatic disable). |
| Description | Your 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.
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 path | Scope | Result |
|---|---|---|
GET /v1/webhooks/endpoints | webhooks:read | Endpoints, newest first (?projectId, ?limit, ?cursor) |
POST /v1/webhooks/endpoints | webhooks:write | 201, the endpoint and its signing secret, shown once |
GET /v1/webhooks/endpoints/{endpointId} | webhooks:read | One endpoint, with limit: { used, limit } |
PATCH /v1/webhooks/endpoints/{endpointId} | webhooks:write | Change url, description, events or enabled |
DELETE /v1/webhooks/endpoints/{endpointId} | webhooks:write | { "deleted": true } |
POST /v1/webhooks/endpoints/{endpointId}/rotate-secret | webhooks:write | A new secret, shown once (rotation) |
POST /v1/webhooks/endpoints/{endpointId}/test | webhooks:write | Sends webhook.test now and reports the result |
POST /v1/webhooks/endpoints/{endpointId}/replay | webhooks:write | 202, bulk replay by time range |
GET /v1/webhooks/deliveries | webhooks:read | The delivery log |
GET /v1/webhooks/deliveries/{deliveryId} | webhooks:read | One delivery, with every attempt |
POST /v1/webhooks/deliveries/{deliveryId}/replay | webhooks:write | 202, sends that delivery again |
GET /v1/webhooks/event-types | webhooks:read | The 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.
Signing secrets
Section titled “Signing secrets”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).
Rotate a secret without downtime
Section titled “Rotate a secret without downtime”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:
- Rotate and store the new secret next to the old one in your receiver.
- Deploy a receiver that accepts either secret.
- 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.
Event envelope
Section titled “Event envelope”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.
Event catalog
Section titled “Event catalog”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.
| Event | Status | Sent when |
|---|---|---|
room.created | live | A room was created |
room.started | live | The first participant joined a room |
room.empty | live | The last participant left an open room |
room.idle_timeout | live | An open room has had no participants for the idle period (data.idleSince, data.idleMinutes) |
room.locked | live | A room was locked or unlocked |
room.ended | live | A room was ended |
participant.joined | live | A participant joined a room |
participant.left | live | A participant left a room |
participant.updated | live | A moderator changed a participant (role, permissions, name, metadata, host mute) |
participant.connection_quality | planned | Sampled connection quality (opt-in) |
track.published | live | A participant published a track |
track.unpublished | live | A participant stopped a track |
track.muted | live | A participant muted a track, or a host muted it |
track.unmuted | live | A muted track was unmuted |
recording.requested | live | A recording was requested |
recording.started | live | Capture of a recording started |
recording.stopped | live | Capture 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.ready | live | Every track of a recording is stored |
recording.failed | live | A recording ended failed (captured tracks may be kept) |
recording.composite.ready | live | The composite video and audio files are stored |
recording.composite.failed | live | No composite file could be made |
recording.delivered | live | A recording file was delivered to your own storage |
recording.delivery_failed | live | A recording file could not be delivered to your own storage |
recording.deleted | live | A 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.restored | live | A recording was restored from Trash: data is { recordingId, roomId, restoredAt, by }, with by customer or admin |
recording.purged | live | A 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.queued | live | A recording’s transcript reserved its minutes and is queued: data is { recordingId, roomId, reservedMinutes } (transcription) |
transcript.completed | live | A 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.failed | live | A 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.segment | planned | Not yet available to customers (live captions) |
captions.started | planned | Not yet available to customers |
captions.stopped | planned | Not yet available to customers |
whiteboard.created | live | A whiteboard was created in a room |
whiteboard.archived | live | A whiteboard was archived or deleted |
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.ready | planned | Whiteboard activity |
key.created | live | An API key was created |
key.revoked | live | An API key was revoked |
quota.warning | live | An RTC allowance passed a warning percentage (80 % unless CHAMPREP sets others); once per allowance, billing period and percentage |
quota.exhausted | live | An RTC allowance is used up (subscription, trial and packs); once per allowance and billing period |
subscription.changed | planned | The RTC subscription changed (tier, trial, payment problem) |
webhook.test | live | A test event sent from the console or the API |
webhook.endpoint_disabled | live | One 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.ended | planned | Streaming 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.
Verify every request
Section titled “Verify every request”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: 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>| Scheme | Signed content | HMAC-SHA256 key | Signature |
|---|---|---|---|
| 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 secret | webhook-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_ prefix | X-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-Signaturecarries only the newest secret. A legacy receiver that still holds the previous secret must checkX-RTC-Signatures. - Off-the-shelf Standard Webhooks libraries accept
whsec_secrets directly. For a migratedrtc_…secret, give the librarywhsec_followed by the base64 encoding of the whole secret’s UTF-8 bytes.
Node.js
Section titled “Node.js”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 eventconst 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.
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 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.
Respond, deduplicate and order
Section titled “Respond, deduplicate and order”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.
Retries and automatic disable
Section titled “Retries and automatic disable”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, delivery log and replay
Section titled “Test, delivery log and replay”- Test:
POST /v1/webhooks/endpoints/{endpointId}/testsends awebhook.testevent right away and answers{ deliveryId, eventId, ok, status, latencyMs, error }. - Delivery log:
GET /v1/webhooks/deliverieslists deliveries, newest first, withstate(pending,retry,delivered,dead,cancelled),attempts,lastStatus,lastErrorandlastLatencyMs. Filter with?endpointId,?state,?typeand?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}/replayqueues the delivery again. Replays per delivery and per day are limited (REPLAY_LIMIT,REPLAY_QUOTA); a delivery being sent answersDELIVERY_IN_PROGRESS. - Bulk replay:
POST /v1/webhooks/endpoints/{endpointId}/replaywith{ "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 answers202 { "queued": n }.
Troubleshooting
Section titled “Troubleshooting”- Send a test event and read its
statusanderror. - Read the delivery log’s
lastStatusand 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 forX-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.