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.
Puntos finales
Sección titulada «Puntos finales»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ón | Significado |
|---|---|
| URL | Una 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. |
| Proyecto | Un proyecto o todos los proyectos de la organización (projectId: null). |
| Eventos | Filtros: * 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. |
| Habilitado | Los 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ón | Su 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.
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ón | Resultado |
|---|---|---|
GET /v1/webhooks/endpoints | webhooks:read | Puntos finales, los más recientes primero (?projectId, ?limit, ?cursor) |
POST /v1/webhooks/endpoints | webhooks:write | 201, el punto final y su secreto de firma, que se muestra una sola vez |
GET /v1/webhooks/endpoints/{endpointId} | webhooks:read | Un punto final, con limit: { used, limit } |
PATCH /v1/webhooks/endpoints/{endpointId} | webhooks:write | Modificar url, description, events o enabled |
DELETE /v1/webhooks/endpoints/{endpointId} | webhooks:write | { "deleted": true } |
POST /v1/webhooks/endpoints/{endpointId}/rotate-secret | webhooks:write | Un nuevo secreto, que se muestra una sola vez (rotación) |
POST /v1/webhooks/endpoints/{endpointId}/test | webhooks:write | Envía webhook.test ahora y comunica el resultado |
POST /v1/webhooks/endpoints/{endpointId}/replay | webhooks:write | 202, reproducción masiva por intervalo de tiempo |
GET /v1/webhooks/deliveries | webhooks:read | El registro de entregas |
GET /v1/webhooks/deliveries/{deliveryId} | webhooks:read | Una entrega, con cada intento |
POST /v1/webhooks/deliveries/{deliveryId}/replay | webhooks:write | 202, reenvía dicha entrega |
GET /v1/webhooks/event-types | webhooks:read | El 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.
Secretos de firma
Sección titulada «Secretos de firma»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).
Rotar un secreto sin tiempo de inactividad
Sección titulada «Rotar un secreto sin tiempo de inactividad»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:
- Rote y almacene el nuevo secreto junto al antiguo en su receptor.
- Implemente un receptor que acepte cualquiera de los secretos.
- 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.
Envolvente del evento
Sección titulada «Envolvente del evento»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.
Catálogo de eventos
Sección titulada «Catálogo de eventos»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.
| Evento | Estado | Enviado cuando |
|---|---|---|
room.created | activo | Se ha creado una sala |
room.started | activo | El primer participante se ha unido a una sala |
room.empty | activo | El último participante ha abandonado una sala abierta |
room.idle_timeout | activo | Una sala abierta no ha tenido participantes durante el periodo de inactividad (data.idleSince, data.idleMinutes) |
room.locked | activo | Se ha bloqueado o desbloqueado una sala |
room.ended | activo | Se ha cerrado una sala |
participant.joined | activo | Un participante se ha unido a una sala |
participant.left | activo | Un participante ha abandonado una sala |
participant.updated | activo | Un moderador ha realizado cambios en un participante (función, permisos, nombre, metadatos, silenciamiento por parte del anfitrión) |
participant.connection_quality | previsto | Muestreo de la calidad de la conexión (opcional) |
track.published | activo | Un participante ha publicado una pista |
track.unpublished | activo | Un participante ha detenido una pista |
track.muted | activo | Un participante ha silenciado una pista, o el anfitrión la ha silenciado |
track.unmuted | activo | Se ha desactivado el silencio de una pista |
recording.requested | activo | Se ha solicitado una grabación |
recording.started | activo | Se ha iniciado la captura de una grabación |
recording.stopped | activo | La 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.ready | activo | Cada pista de una grabación se almacena |
recording.failed | activo | La finalización de una grabación ha fallado (es posible que se conserven las pistas capturadas) |
recording.composite.ready | activo | Los archivos de vídeo y audio compuestos se almacenan |
recording.composite.failed | activo | No se ha podido crear ningún archivo compuesto |
recording.delivered | activo | Se ha transferido un archivo de grabación a su propio espacio de almacenamiento |
recording.delivery_failed | activo | No se ha podido entregar un archivo de grabación a su propio espacio de almacenamiento |
recording.deleted | activo | Se 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.restored | activo | Se ha recuperado una grabación de la Papelera: data es { recordingId, roomId, restoredAt, by }, con by customer o admin |
recording.purged | activo | Se 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.queued | activo | La transcripción de una grabación ha reservado sus minutos y se encuentra en cola: data es { recordingId, roomId, reservedMinutes } (transcripción) |
transcript.completed | activo | La 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.failed | activo | La 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.segment | previsto | Aún no disponible para los clientes (subtítulos en directo) |
captions.started | previsto | Aún no está disponible para los clientes |
captions.stopped | previsto | Aún no está disponible para los clientes |
whiteboard.created | activo | Se ha creado una pizarra en una sala |
whiteboard.archived | activo | Se ha archivado o eliminado una pizarra |
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.ready | previsto | Actividad de la pizarra |
key.created | activo | Se ha creado una claveAPI |
key.revoked | activo | Se ha revocado una claveAPI |
quota.warning | activo | Una 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.exhausted | activo | Se agota una asignación de RTC (suscripción, periodo de prueba y paquetes); una vez por asignación y periodo de facturación |
subscription.changed | previsto | La suscripción a RTC ha cambiado (nivel, periodo de prueba, problema de pago) |
webhook.test | activo | Un evento de prueba enviado desde la consola o desde el API |
webhook.endpoint_disabled | activo | Uno 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.ended | previsto | Transmisió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.
Verifique cada solicitud
Sección titulada «Verifique cada solicitud»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: 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>| Esquema | Contenido firmado | Clave HMAC-SHA256 | Firma |
|---|---|---|---|
| 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 completo | webhook-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_ prefijo | X-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-Signaturesolo contiene el secreto más reciente. Un receptor heredado que aún conserve el secreto anterior debe comprobarX-RTC-Signatures. - Las bibliotecas estándar de webhooks disponibles en el mercado aceptan
whsec_secretos directamente. Para unrtc_…secreto, facilite a la bibliotecawhsec_seguido de la codificación base64 de los bytes UTF-8 del secreto completo.
Node.js
Sección titulada «Node.js»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 eventconst 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 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 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.
Responder, deduplicar y ordenar
Sección titulada «Responder, deduplicar y ordenar»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.
Reintentos y desactivación automática
Sección titulada «Reintentos y desactivación automática»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, registro de entrega y reproducción
Sección titulada «Prueba, registro de entrega y reproducción»- Prueba:
POST /v1/webhooks/endpoints/{endpointId}/testenvía unwebhook.testevento de inmediato y las respuestas{ deliveryId, eventId, ok, status, latencyMs, error }. - Registro de entrega:
GET /v1/webhooks/deliveriesenumera las entregas, de más reciente a más antigua, constate(pending,retry,delivered,dead,cancelled),attempts,lastStatus,lastErrorylastLatencyMs. Filtre con?endpointId,?state,?typey?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}/replayPonga 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 respuestaDELIVERY_IN_PROGRESS. - Reproducción masiva:
POST /v1/webhooks/endpoints/{endpointId}/replaycon{ "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 respuestas202 { "queued": n }.
Solución de problemas
Sección titulada «Solución de problemas»- Envíe un evento de prueba y lea su
statusyerror. - Lea el registro de entrega
lastStatusy 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 paraX-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.