Ir al contenido
Documentation

Webhooks de RTC

RTC envía eventos sobre sus salas, participantes, grabaciones y cuenta a webhook puntos finales que usted registre. Cada punto final tiene su propia URL, filtros de eventos, secretos de firma y registro de entrega. La entrega es al menos una vez: deduplicar en el evento id antes de actuar.

Gestione los puntos finales en la consola de RTC en Webhooks, a través de la API con su sesión de consola, o con una claveAPI de proyecto que tenga el webhooks:read o webhooks:write ámbito. Una clave de proyecto solo ve y gestiona los puntos finales de su propio proyecto.

ConfiguraciónSignificado
URLUna URL pública HTTPS en el puerto 443. No se siguen las redirecciones y se rechazan las direcciones privadas o reservadas, tanto al guardar como en cada intento.
ProyectoUn proyecto o todos los proyectos de la organización (projectId: null).
EventosFiltros: * para cada evento, una familia como recording.*, o un tipo como room.ended. Se rechaza cualquier filtro que no coincida con ningún tipo conocido.
HabilitadoLos puntos finales desactivados no reciben nada. RTC desactiva un punto final por sí mismo cuando este sigue fallando (véase Reintentos y desactivación automática).
DescripciónSu propia etiqueta, de hasta 500 caracteres.

El número de puntos finales depende de su plan. Crear uno más de los que permite el plan permite respuestas 409 con el código WEBHOOK_ENDPOINT_LIMIT.

Ventana de terminal
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"] }'
Método y rutaÁmbito de aplicaciónResultado
GET /v1/webhooks/endpointswebhooks:readPuntos finales, los más recientes primero (?projectId, ?limit, ?cursor)
POST /v1/webhooks/endpointswebhooks:write201, el punto final y su secreto de firma, que se muestra una sola vez
GET /v1/webhooks/endpoints/{endpointId}webhooks:readUn punto final, con limit: { used, limit }
PATCH /v1/webhooks/endpoints/{endpointId}webhooks:writeModificar url, description, events o enabled
DELETE /v1/webhooks/endpoints/{endpointId}webhooks:write{ "deleted": true }
POST /v1/webhooks/endpoints/{endpointId}/rotate-secretwebhooks:writeUn nuevo secreto, que se muestra una sola vez (rotación)
POST /v1/webhooks/endpoints/{endpointId}/testwebhooks:writeEnvía webhook.test ahora y comunica el resultado
POST /v1/webhooks/endpoints/{endpointId}/replaywebhooks:write202, reproducción masiva por intervalo de tiempo
GET /v1/webhooks/deliverieswebhooks:readEl registro de entregas
GET /v1/webhooks/deliveries/{deliveryId}webhooks:readUna entrega, con cada intento
POST /v1/webhooks/deliveries/{deliveryId}/replaywebhooks:write202, reenvía dicha entrega
GET /v1/webhooks/event-typeswebhooks:readEl catálogo de eventos

Un objeto de punto final nunca contiene un valor secreto. Enumera cada secreto activo id, es breve prefix (por ejemplo whsec_Ab12), createdAt y, durante una rotación, expiresAt. Además, genera un informe status (active o disabled), disabledReason (manual, failing, gone o admin) y health (consecutiveFailures, lastSuccessAt, lastFailureAt, failingSince).

Un punto final CHAMPREP con la función desactivada (disabledReason: "admin") no se puede activar ni enviar un evento de prueba (WEBHOOK_ENDPOINT_ADMIN_DISABLED), y su URL no puede añadirse de nuevo como un nuevo punto de conexión (WEBHOOK_URL_ADMIN_DISABLED). Póngase en contacto con el servicio de asistencia.

Las listas devuelven una matriz JSON. Cuando existen más elementos, la X-Next-Cursor El encabezado de respuesta contiene el cursor para la página siguiente; devuélvalo como ?cursor. ?limit admite valores de 1 a 200.

Los espacios de trabajo que hayan configurado el webhook único anterior (PUT /v1/webhook) manténgalo: ahora aparece como un punto final para todos los proyectos y todos los eventos, marcado legacy: true, y el /v1/webhook las rutas siguen funcionando.

El secreto de un nuevo punto final tiene el formato whsec_ seguido de base64. Se muestra una vez, en la respuesta a la solicitud de creación o rotación, y RTC lo almacena cifrado. Guárdelo en el gestor de secretos de su receptor; nadie podrá mostrárselo de nuevo, ni siquiera el servicio de asistenciaCHAMPREP. Si lo pierde, rote el secreto.

Nunca pegue un secreto de firma en un chat, un ticket o un registro. El CHAMPREP AI asistente puede mostrar una lista, crear, probar y reproducir puntos finales por usted, pero nunca ve ni muestra un secreto: obtenga uno en la consola (Webhooks, a continuación Rotar secreto).

POST /v1/webhooks/endpoints/{endpointId}/rotate-secret con { "overlapHours": 24 } crea un nuevo secreto y mantiene válidos los anteriores durante el periodo de solapamiento (de 0 a 72 horas; 24 por defecto). Durante el periodo de solapamiento cada entrega se firma con cada secreto activo, de modo que los destinatarios puedan realizar la transición a su propio ritmo:

  1. Rote y almacene el nuevo secreto junto al antiguo en su receptor.
  2. Implemente un receptor que acepte cualquiera de los secretos.
  3. Cuando todas las instancias utilicen el nuevo secreto, elimine el antiguo. Deja de firmar cuando finaliza el solapamiento (previousSecretsExpireAt).

Uso overlapHours: 0 cuando aún ningún receptor utiliza el punto final, por ejemplo, para obtener un secreto para un punto final creado por el asistente de IA.

Los nuevos puntos finales utilizan la APIversión 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" }
}

El punto final heredado conserva la envolvente anterior, { id, type, createdAt, projectId, data }. Un punto final apiVersion fija la forma de la carga útil que recibe; véase control de versiones.

Los ID anteriores son meramente ilustrativos. Trátelos id como una cadena opaca: algunas son UUID, otras son derivadas, como recording-ready:<uuid>. projectId puede estar ausente en el caso de un evento a nivel de organización, y roomId está presente en los eventos de la sala.

GET /v1/webhooks/event-types devuelve la lista oficial, cada tipo con una descripción y status: live (enviada) o planned (un nombre reservado al que quizá ya esté suscrito; aún no se ha enviado nada). Algunos eventos en directo solo se envían cuando la función correspondiente está habilitada para su espacio de trabajo.

EventoEstadoEnviado cuando
room.createdactivoSe ha creado una sala
room.startedactivoEl primer participante se ha unido a una sala
room.emptyactivoEl último participante ha abandonado una sala abierta
room.idle_timeoutactivoUna sala abierta no ha tenido participantes durante el periodo de inactividad (data.idleSince, data.idleMinutes)
room.lockedactivoSe ha bloqueado o desbloqueado una sala
room.endedactivoSe ha cerrado una sala
participant.joinedactivoUn participante se ha unido a una sala
participant.leftactivoUn participante ha abandonado una sala
participant.updatedactivoUn moderador ha realizado cambios en un participante (función, permisos, nombre, metadatos, silenciamiento por parte del anfitrión)
participant.connection_qualityprevistoMuestreo de la calidad de la conexión (opcional)
track.publishedactivoUn participante ha publicado una pista
track.unpublishedactivoUn participante ha detenido una pista
track.mutedactivoUn participante ha silenciado una pista, o el anfitrión la ha silenciado
track.unmutedactivoSe ha desactivado el silencio de una pista
recording.requestedactivoSe ha solicitado una grabación
recording.startedactivoSe ha iniciado la captura de una grabación
recording.stoppedactivoLa captura se detuvo, una vez por grabación, con el reason (requested, room_ended, max_duration, limit, tenant_inactive, shutdown, allowance cuando se agoten los minutos de grabación, billing_unavailable o error)
recording.readyactivoCada pista de una grabación se almacena
recording.failedactivoLa finalización de una grabación ha fallado (es posible que se conserven las pistas capturadas)
recording.composite.readyactivoLos archivos de vídeo y audio compuestos se almacenan
recording.composite.failedactivoNo se ha podido crear ningún archivo compuesto
recording.deliveredactivoSe ha transferido un archivo de grabación a su propio espacio de almacenamiento
recording.delivery_failedactivoNo se ha podido entregar un archivo de grabación a su propio espacio de almacenamiento
recording.deletedactivoSe ha enviado una grabación a la Papelera: data es { recordingId, roomId, reason, deletedAt, purgeAt }, con reason customer (la ha eliminado usted) o retention (ha finalizado su periodo de retención), y purgeAt cuando se elimina automáticamente (30 días después; se soluciona al enviarla a la Papelera, null mientras la eliminación automática de la Papelera está desactivada). Se puede recuperar hasta ese momento.
recording.restoredactivoSe ha recuperado una grabación de la Papelera: data es { recordingId, roomId, restoredAt, by }, con by customer o admin
recording.purgedactivoSe ha eliminado definitivamente una grabación de la Papelera: data es { recordingId, roomId, reason, purgedAt }, con reason customer (la ha eliminado de la Papelera), expired (se elimina automáticamente tras 30 días) o admin (CHAMPREPsoporte)
transcript.queuedactivoLa transcripción de una grabación ha reservado sus minutos y se encuentra en cola: data es { recordingId, roomId, reservedMinutes } (transcripción)
transcript.completedactivoLa transcripción de una grabación está lista: data es { recordingId, roomId, segments, durationMs, billedMinutes, truncated }, con truncated true cuando se agotó la asignación durante una intensa interferencia. Nunca el texto.
transcript.failedactivoLa transcripción de una grabación ha fallado y no se ha cobrado nada: data es { recordingId, roomId, error }, además de code (RTC_ALLOWANCE_EXHAUSTED, BILLING_UNAVAILABLE, CANCELLED o RECORDING_LENGTH_UNKNOWN) y offers cuando el motivo sea la asignación
transcript.segmentprevistoAún no disponible para los clientes (subtítulos en directo)
captions.startedprevistoAún no está disponible para los clientes
captions.stoppedprevistoAún no está disponible para los clientes
whiteboard.createdactivoSe ha creado una pizarra en una sala
whiteboard.archivedactivoSe ha archivado o eliminado una pizarra
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.readyprevistoActividad de la pizarra
key.createdactivoSe ha creado una claveAPI
key.revokedactivoSe ha revocado una claveAPI
quota.warningactivoUna asignación de RTC ha superado un porcentaje de aviso (80 %, salvo que se establezcaCHAMPREP otro valor); una vez por asignación, período de facturación y porcentaje
quota.exhaustedactivoSe agota una asignación de RTC (suscripción, periodo de prueba y paquetes); una vez por asignación y periodo de facturación
subscription.changedprevistoLa suscripción a RTC ha cambiado (nivel, periodo de prueba, problema de pago)
webhook.testactivoUn evento de prueba enviado desde la consola o desde el API
webhook.endpoint_disabledactivoUno de sus puntos de conexión se desactivó tras fallar o responder 410: data es { endpointId, url, host, reason }. url se refiere únicamente al esquema, el host y la ruta, nunca a la cadena de consulta; host es el host por sí solo; reason es failing o gone.
egress.started, egress.ended, ingress.started, ingress.endedprevistoTransmisión e ingesta (aún no disponible)

Los eventos contienen identificadores, no nombres de visualización, tokens, direcciones IP ni archivos multimedia. Conciliar el estado relevante con el API en lugar de basarse en un único evento.

Cada entrega incluye dos esquemas de firma independientes. Verifique uno de ellos, a lo largo de la bytes exactos del cuerpo de la solicitud sin procesar, antes de analizar el JSON o realizar cualquier acción. Nunca analice ni vuelva a serializar el cuerpo para su verificación.

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>
EsquemaContenido firmadoClave HMAC-SHA256Firma
Webhooks estándar (recomendado)<webhook-id>.<webhook-timestamp>.<raw body>whsec_… secretos: la parte decodificada en base64 que aparece tras el whsec_ prefijo. Secretos heredados migrados rtc_… secretos: los bytes UTF-8 del secreto completowebhook-signature: separados por espacios v1,<base64>, uno por cada secreto activo
RTC (heredado)<X-RTC-Timestamp>.<raw body>Los bytes UTF-8 de toda la cadena del secreto, incluyendo cualquier whsec_ o rtc_ prefijoX-RTC-Signature: v1=<hex> para el secreto más reciente; X-RTC-Signatures: cada secreto activo, separados por espacios

Para ambos esquemas:

  • Rechace cualquier marca de tiempo que se desvíe más de cinco minutos de su reloj.
  • Compare las firmas en tiempo constante y acepte la solicitud cuando cualquiera La firma indicada coincide con uno de sus secretos.
  • Durante un solapamiento de rotación, X-RTC-Signature solo contiene el secreto más reciente. Un receptor heredado que aún conserve el secreto anterior debe comprobar X-RTC-Signatures.
  • Las bibliotecas estándar de webhooks disponibles en el mercado aceptan whsec_ secretos directamente. Para un rtc_… secreto, facilite a la biblioteca whsec_ seguido de la codificación base64 de los bytes UTF-8 del secreto completo.

El Ejemplo de verificación implementa ambos esquemas sin dependencias:

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.

Durante una rotación, llame al verificador una vez por cada secreto que posea.

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 debe ser una correspondencia que no distinga entre mayúsculas y minúsculas, como request.headers en Flask, Django o Starlette, y raw_body el cuerpo sin analizar (request.get_data() en Flask, request.body En Django, await request.body() en Starlette).

Estos ejemplos son orientaciones para la integración del receptor, no servidores completos. Establezca un límite para el cuerpo de la solicitud, gestione el JSON mal formado y valide la envoltura.

Devuelva un 2xx Responda sin demora tras aceptar de forma permanente un evento verificado y realice las tareas más largas de forma asíncrona. Cada intento caduca tras 5 segundos. Cualquier otro estado, una redirección o una caducación se considera un intento fallido.

Persistir event.id de forma atómica y procese cada evento una sola vez; un conjunto en memoria no es suficiente entre reinicios o varias instancias del receptor. La comprobación de la marca de tiempo por sí sola no impide una repetición dentro de la ventana aceptada. El orden no está garantizado: utilice marcas de tiempo en data y el API para resolver el estado actual.

Una entrega fallida se vuelve a intentar con retroceso exponencial y fluctuación durante aproximadamente 24 horas (12 intentos), tras lo cual se marca dead. Cada intento se firma de nuevo con los secretos activos del punto final y una nueva marca de tiempo.

Cada intento caduca tras 5 segundos. RTC desactiva un punto final (disabledReason: "failing") cuando se cumpla cualquiera de estas condiciones:

  • ha agotado el tiempo de espera 25 veces seguidas y, además, lleva fallando desde hace al menos una hora;
  • ha estado fallando de forma continuada durante 24 horas (CHAMPREPpuede establecerse otro periodo).

Lo desactiva de inmediato ("gone") cuando responde 410 Gone. Se notifica al propietario de la organización y se envía un webhook.endpoint_disabled El evento se envía a sus otros puntos finales. Corrija el receptor y, a continuación, vuelva a habilitar el punto final (PATCH con { "enabled": true }); al habilitarlo, se borra su estado de fallo.

  • Prueba: POST /v1/webhooks/endpoints/{endpointId}/test envía un webhook.test evento de inmediato y las respuestas { deliveryId, eventId, ok, status, latencyMs, error }.
  • Registro de entrega: GET /v1/webhooks/deliveries enumera las entregas, de más reciente a más antigua, con state (pending, retry, delivered, dead, cancelled), attempts, lastStatus, lastError y lastLatencyMs. Filtre con ?endpointId, ?state, ?type y ?eventId. Una entrega (GET /v1/webhooks/deliveries/{deliveryId}) añade cada intento con su estado, latencia y el primer 1 KB de la respuesta de su receptor, así como el propio evento. El registro se conserva durante un periodo limitado.
  • Repetición uno: POST /v1/webhooks/deliveries/{deliveryId}/replay Ponga en cola la entrega de nuevo. Las reproducciones por entrega y por día están limitadas (REPLAY_LIMIT, REPLAY_QUOTA); se envía una entrega y se obtiene una respuesta DELIVERY_IN_PROGRESS.
  • Reproducción masiva: POST /v1/webhooks/endpoints/{endpointId}/replay con { "from": "2026-11-08T00:00:00Z", "to": "2026-11-08T06:00:00Z", "types": ["recording.*"], "onlyFailed": true } Las colas contienen los eventos coincidentes de ese intervalo de tiempo para el punto final, con un máximo de 1000 por solicitud, y las respuestas 202 { "queued": n }.

  • Envíe un evento de prueba y lea su status y error.
  • Lea el registro de entrega lastStatus y el extracto de la respuesta del intento.
  • Compruebe que verifica los bytes sin procesar con la clave correcta para el esquema (la parte decodificada whsec_ parte para los webhooks estándar, la cadena completa para X-RTC-Signature).
  • Compruebe la desviación horaria, las redirecciones y que el punto final esté habilitado.

Nunca registre el secreto de firma, las solicitudes sin procesar que contengan la firma ni las credenciales de los participantes durante la resolución de problemas.