Webhooks do RTC
O RTC envia eventos sobre suas salas, participantes, gravações e conta para o webhook pontos de extremidade que o senhor registrar. Cada endpoint possui sua própria URL, filtros de eventos, segredos de assinatura e registro de entrega. A entrega é pelo menos uma vez: deduplicação no evento id antes de agir.
Pontos de extremidade
Seção intitulada “Pontos de extremidade”Gerencie pontos de extremidade no console do RTC em Webhooks, por meio do API com sua sessão do console, ou com uma chaveAPI de projeto que possua o webhooks:read
ou webhooks:write escopo. Uma chave de projeto apenas visualiza e gerencia os endpoints do seu próprio projeto.
| Configuração | Significado |
|---|---|
| URL | Uma URL HTTPS pública na porta 443. Redirecionamentos não são seguidos e endereços privados ou reservados são recusados, tanto ao salvar quanto em cada tentativa. |
| Projeto | Um projeto ou todos os projetos da organização (projectId: null). |
| Eventos | Filtros: * para cada evento, uma família como recording.*, ou um tipo, como room.ended. Um filtro que não corresponda a nenhum tipo conhecido é recusado. |
| Ativado | Os endpoints desativados não recebem nada. O RTC desativa um endpoint automaticamente quando ele continua falhando (consulte Novas tentativas e desativação automática). |
| Descrição | Seu próprio rótulo, com até 500 caracteres. |
O número de pontos finais depende do seu plano. Criar um a mais do que o previsto no plano permite respostas 409 com o 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 e caminho | Escopo | Resultado |
|---|---|---|
GET /v1/webhooks/endpoints | webhooks:read | Pontos de extremidade, os mais recentes primeiro (?projectId, ?limit, ?cursor) |
POST /v1/webhooks/endpoints | webhooks:write | 201, o endpoint e seu segredo de assinatura, exibidos uma vez |
GET /v1/webhooks/endpoints/{endpointId} | webhooks:read | Um endpoint, com limit: { used, limit } |
PATCH /v1/webhooks/endpoints/{endpointId} | webhooks:write | Alterar url, description, events ou enabled |
DELETE /v1/webhooks/endpoints/{endpointId} | webhooks:write | { "deleted": true } |
POST /v1/webhooks/endpoints/{endpointId}/rotate-secret | webhooks:write | Um novo segredo, exibido uma vez (rotação) |
POST /v1/webhooks/endpoints/{endpointId}/test | webhooks:write | Envia webhook.test agora e informa o resultado |
POST /v1/webhooks/endpoints/{endpointId}/replay | webhooks:write | 202, reprodução em lote por intervalo de tempo |
GET /v1/webhooks/deliveries | webhooks:read | O registro de entregas |
GET /v1/webhooks/deliveries/{deliveryId} | webhooks:read | Uma entrega, com todas as tentativas |
POST /v1/webhooks/deliveries/{deliveryId}/replay | webhooks:write | 202, reenvia essa entrega |
GET /v1/webhooks/event-types | webhooks:read | O catálogo de eventos |
Um objeto de endpoint nunca contém um valor secreto. Ele lista cada segredo ativo
id, resumindo prefix (por exemplo whsec_Ab12), createdAt e, durante uma rotação, expiresAt. Ele também gera relatórios status (active ou disabled),
disabledReason (manual, failing, gone ou admin) e health
(consecutiveFailures, lastSuccessAt, lastFailureAt, failingSince).
Um endpoint com o suporteCHAMPREP desativado (disabledReason: "admin") não pode ser ativado nem receber um evento de teste (WEBHOOK_ENDPOINT_ADMIN_DISABLED), e sua URL não pode ser adicionada novamente como um novo endpoint (WEBHOOK_URL_ADMIN_DISABLED). Entre em contato com o suporte.
As listagens retornam um array JSON. Quando há mais itens, o X-Next-Cursor O cabeçalho de resposta contém o cursor para a próxima página; retorne-o como ?cursor.
?limit aceita valores de 1 a 200.
Espaços de trabalho que configuraram o webhook único anterior (PUT /v1/webhook) mantenha-o: agora ele aparece como um endpoint para todos os projetos e todos os eventos, marcado
legacy: true, e o /v1/webhook as rotas continuam funcionando.
Segredos de assinatura
Seção intitulada “Segredos de assinatura”O segredo de um novo endpoint tem o formato whsec_ seguido de base64. É exibido
uma vez, na resposta à solicitação de criação ou rotação, e o RTC o armazena criptografado. Armazene-o no gerenciador de segredos do seu destinatário; ninguém poderá mostrá-lo a você novamente, incluindo o suporteCHAMPREP. Caso o perca, faça a rotação do segredo.
Nunca cole um segredo de assinatura em um chat, ticket ou log. O CHAMPREP AI assistente pode listar, criar, testar e reproduzir endpoints para você, mas ele nunca visualiza nem exibe um segredo: obtenha um no console (Webhooks, em seguida Alternar segredo).
Alternar um segredo sem tempo de inatividade
Seção intitulada “Alternar um segredo sem tempo de inatividade”POST /v1/webhooks/endpoints/{endpointId}/rotate-secret com
{ "overlapHours": 24 } cria um novo segredo e mantém os anteriores válidos durante o período de sobreposição (0 a 72 horas, 24 por padrão). Durante o período de sobreposição cada entrega é assinada com todos os segredos ativos, para que os destinatários possam fazer a transição em seu próprio ritmo:
- Faça a rotação e armazene o novo segredo ao lado do antigo em seu receptor.
- Implemente um receptor que aceite qualquer um dos segredos.
- Quando todas as instâncias estiverem utilizando o novo segredo, remova o antigo. A assinatura será interrompida quando a sobreposição terminar (
previousSecretsExpireAt).
Utilização overlapHours: 0 quando nenhum receptor utiliza o endpoint ainda, por exemplo, para obter um segredo para um endpoint criado pelo assistente de IA.
Envelope do evento
Seção intitulada “Envelope do evento”Novos endpoints utilizam a versãoAPI 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" }}O endpoint legado mantém o envelope anterior,
{ id, type, createdAt, projectId, data }. Um endpoint’s apiVersion fixa a forma da carga útil que recebe; consulte controle de versão.
Os IDs acima são meramente ilustrativos. Trate id como uma sequência opaca: algumas são UUIDs, outras são derivadas, tais como recording-ready:<uuid>. projectId pode estar ausente para um evento no nível da organização, e roomId está presente para eventos da sala.
Catálogo de eventos
Seção intitulada “Catálogo de eventos”GET /v1/webhooks/event-types retorna a lista oficial, cada tipo com uma descrição e status: live (enviada) ou planned (um nome reservado ao qual o(a) senhor(a) talvez já esteja inscrito(a); nada foi enviado ainda). Alguns eventos ao vivo só são enviados quando o recurso relacionado está habilitado para o seu espaço de trabalho.
| Evento | Status | Enviado quando |
|---|---|---|
room.created | ativo | Uma sala foi criada |
room.started | ativo | O primeiro participante entrou em uma sala |
room.empty | ativo | O último participante saiu de uma sala aberta |
room.idle_timeout | ativo | Uma sala aberta não teve participantes durante o período de inatividade (data.idleSince, data.idleMinutes) |
room.locked | ativo | Uma sala foi bloqueada ou desbloqueada |
room.ended | ativo | Uma sala foi encerrada |
participant.joined | ativo | Um participante entrou em uma sala |
participant.left | ativo | Um participante saiu de uma sala |
participant.updated | ativo | Um moderador alterou um participante (função, permissões, nome, metadados, silenciamento pelo anfitrião) |
participant.connection_quality | planejado | Amostragem da qualidade da conexão (opcional) |
track.published | ativo | Um participante publicou uma faixa |
track.unpublished | ativo | Um participante interrompeu uma faixa |
track.muted | ativo | Um participante silenciou uma faixa, ou um anfitrião a silenciou |
track.unmuted | ativo | Uma faixa silenciada teve o silêncio desativado |
recording.requested | ativo | Foi solicitada uma gravação |
recording.started | ativo | A captura de uma gravação foi iniciada |
recording.stopped | ativo | A captura foi interrompida, uma vez por gravação, com o reason (requested, room_ended, max_duration, limit, tenant_inactive, shutdown, allowance quando os minutos de gravação se esgotarem, billing_unavailable ou error) |
recording.ready | ativo | Cada faixa de uma gravação é armazenada |
recording.failed | ativo | A gravação foi encerrada com falha (as faixas capturadas podem ser mantidas) |
recording.composite.ready | ativo | Os arquivos de vídeo e áudio compostos são armazenados |
recording.composite.failed | ativo | Não foi possível criar um arquivo composto |
recording.delivered | ativo | Um arquivo de gravação foi entregue em seu próprio armazenamento |
recording.delivery_failed | ativo | Não foi possível entregar um arquivo de gravação no seu próprio armazenamento |
recording.deleted | ativo | Uma gravação foi enviada para a Lixeira: data é { recordingId, roomId, reason, deletedAt, purgeAt }, com reason customer (você a excluiu) ou retention (o prazo de retenção expirou), e purgeAt quando for excluída automaticamente (30 dias depois; o processo é fixo quando a gravação é enviada para a Lixeira, null enquanto a exclusão automática da Lixeira estiver desativada). Ela pode ser restaurada até esse momento. |
recording.restored | ativo | Uma gravação foi restaurada da Lixeira: data é { recordingId, roomId, restoredAt, by }, com by customer ou admin |
recording.purged | ativo | Uma gravação foi excluída permanentemente da Lixeira: data é { recordingId, roomId, reason, purgedAt }, com reason customer (você a excluiu da Lixeira), expired (excluído automaticamente após 30 dias) ou admin (CHAMPREPsuporte) |
transcript.queued | ativo | A transcrição de uma gravação reservou seus minutos e está na fila: data é { recordingId, roomId, reservedMinutes } (transcrição) |
transcript.completed | ativo | A transcrição de uma gravação está pronta: data é { recordingId, roomId, segments, durationMs, billedMinutes, truncated }, com truncated true quando a cota se esgotou durante intenso tráfego cruzado. Nunca o texto. |
transcript.failed | ativo | A transcrição de uma gravação falhou e nada foi cobrado: data é { recordingId, roomId, error }, além de code (RTC_ALLOWANCE_EXHAUSTED, BILLING_UNAVAILABLE, CANCELLED ou RECORDING_LENGTH_UNKNOWN) e offers quando a cota for o motivo |
transcript.segment | planejado | Ainda não disponível para os clientes (legendas em tempo real) |
captions.started | planejado | Ainda não disponível para os clientes |
captions.stopped | planejado | Ainda não disponível para os clientes |
whiteboard.created | ativo | Foi criado um quadro branco em uma sala |
whiteboard.archived | ativo | Um quadro branco foi arquivado ou excluído |
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.ready | planejado | Atividade no quadro branco |
key.created | ativo | Foi criada uma chaveAPI |
key.revoked | ativo | Uma chaveAPI foi revogada |
quota.warning | ativo | Uma cota de RTC ultrapassou uma porcentagem de alerta (80 %, a menos que CHAMPREP defina outros valores); uma vez por cota, período de faturamento e porcentagem |
quota.exhausted | ativo | Uma cota de RTC é consumida (assinatura, período de teste e pacotes); uma vez por cota e por período de faturamento |
subscription.changed | planejado | A assinatura do RTC foi alterada (plano, período de teste, problema de pagamento) |
webhook.test | ativo | Um evento de teste enviado a partir do console ou do API |
webhook.endpoint_disabled | ativo | Um de seus endpoints foi desativado após falhar ou responder 410: data é { endpointId, url, host, reason }. url refere-se apenas ao esquema, ao host e ao caminho, nunca à string de consulta; host é o host por si só; reason é failing ou gone. |
egress.started, egress.ended, ingress.started, ingress.ended | planejado | Streaming e ingestão (ainda não disponível) |
Os eventos contêm identificadores, e não nomes de exibição, tokens, endereços IP ou mídia. Reconcilie estados importantes com o API em vez de depender de um único evento.
Verifique cada solicitação
Seção intitulada “Verifique cada solicitação”Cada entrega contém dois esquemas de assinatura independentes. Verifique um de cada um deles, ao longo do bytes exatos do corpo da solicitação em formato bruto, antes de analisar o JSON ou executar qualquer ação. Nunca analise e resserialize o corpo para verificação.
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 | Conteúdo assinado | Chave HMAC-SHA256 | Assinatura |
|---|---|---|---|
| Webhooks padrão (recomendado) | <webhook-id>.<webhook-timestamp>.<raw body> | whsec_… segredos: a parte decodificada em base64 após o whsec_ prefixo. Legado migrado rtc_… segredos: os bytes UTF-8 do segredo completo | webhook-signature: separados por espaço v1,<base64>, um por segredo ativo |
| RTC (legado) | <X-RTC-Timestamp>.<raw body> | Os bytes UTF-8 de toda a string secreta, incluindo qualquer whsec_ ou rtc_ prefixo | X-RTC-Signature: v1=<hex> para o segredo mais recente; X-RTC-Signatures: cada segredo ativo, separados por espaço |
Para ambos os esquemas:
- Rejeite um carimbo de data/hora com diferença superior a cinco minutos em relação ao seu relógio.
- Compare as assinaturas em tempo constante e aceite a solicitação quando qualquer A assinatura listada corresponde a um de seus segredos.
- Durante um sobreposição de rotação,
X-RTC-Signaturecarrega apenas o segredo mais recente. Um receptor legado que ainda possua o segredo anterior deve verificarX-RTC-Signatures. - Bibliotecas padrão de Webhooks prontas para uso aceitam
whsec_segredos diretamente. Para um migradortc_…segredo, forneça à bibliotecawhsec_seguido pela codificação base64 dos bytes UTF-8 do segredo completo.
Node.js
Seção intitulada “Node.js”O exemplo de verificação implementa ambos os esquemas sem dependências:
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 uma rotação, chame o verificador uma vez por cada segredo que você possua.
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 deve ser um mapeamento que não distingue maiúsculas de minúsculas, como request.headers no Flask, Django ou Starlette, e raw_body o corpo não analisado (request.get_data() no Flask, request.body no Django, await request.body()
(no Starlette).
Esses exemplos servem como orientação para integração do receptor, não como servidores completos. Defina um limite para o corpo da solicitação, trate JSON malformado e valide o envelope.
Responda, deduplique e ordene
Seção intitulada “Responda, deduplique e ordene”Retorne um 2xx Responda prontamente após aceitar de forma duradoura um evento verificado e realize tarefas mais demoradas de forma assíncrona. Cada tentativa expira após 5 segundos. Qualquer outro status, um redirecionamento ou um tempo limite expirado conta como uma tentativa malsucedida.
Persistir event.id de forma atômica e processe cada evento uma única vez; um conjunto na memória não é suficiente entre reinicializações ou várias instâncias do receptor. A verificação do carimbo de data/hora por si só não impede uma repetição dentro da janela aceita. A ordenação não é garantida: utilize carimbos de data/hora em data e o API para resolver o estado atual.
Novas tentativas e desativação automática
Seção intitulada “Novas tentativas e desativação automática”Uma entrega com falha é repetida com recuo exponencial e jitter por cerca de 24 horas (12 tentativas) e, em seguida, marcada dead. Cada tentativa é assinada novamente com os segredos ativos do endpoint e um novo carimbo de data/hora.
Cada tentativa expira após 5 segundos. O RTC desativa um endpoint (disabledReason: "failing") quando ocorrer qualquer uma das seguintes situações:
- ele atingiu o tempo limite 25 vezes consecutivas e também vem apresentando falhas há pelo menos 1 hora;
- ele estiver apresentando falhas continuamente por 24 horas (CHAMPREPpode-se definir outro período).
Ele o desativa imediatamente ("gone") quando ele responder 410 Gone. O proprietário da organização é notificado, e um webhook.endpoint_disabled O evento é enviado aos seus outros pontos de extremidade. Corrija o receptor e, em seguida, habilite o ponto de extremidade novamente (PATCH com { "enabled": true }); ativar a função limpa seu estado de falha.
Teste, registro de entrega e repetição
Seção intitulada “Teste, registro de entrega e repetição”- Teste:
POST /v1/webhooks/endpoints/{endpointId}/testenvia umwebhook.testevento imediatamente e as respostas{ deliveryId, eventId, ok, status, latencyMs, error }. - Registro de entrega:
GET /v1/webhooks/deliverieslista as entregas, da mais recente à mais antiga, comstate(pending,retry,delivered,dead,cancelled),attempts,lastStatus,lastErrorelastLatencyMs. Filtre com?endpointId,?state,?typee?eventId. Uma entrega (GET /v1/webhooks/deliveries/{deliveryId}) adiciona cada tentativa com seu status, latência e os primeiros 1 KB da resposta do seu receptor, além do próprio evento. O registro é mantido por um período limitado. - Repetição um:
POST /v1/webhooks/deliveries/{deliveryId}/replayEnfileira a entrega novamente. As repetições por entrega e por dia são limitadas (REPLAY_LIMIT,REPLAY_QUOTA); uma entrega sendo enviada respondeDELIVERY_IN_PROGRESS. - Reprodução em massa:
POST /v1/webhooks/endpoints/{endpointId}/replaycom{ "from": "2026-11-08T00:00:00Z", "to": "2026-11-08T06:00:00Z", "types": ["recording.*"], "onlyFailed": true }coloca na fila os eventos correspondentes a esse intervalo de tempo para o endpoint, no máximo 1.000 por solicitação, e as respostas202 { "queued": n }.
Solução de problemas
Seção intitulada “Solução de problemas”- Envie um evento de teste e leia seu
statuseerror. - Leia o log de entrega
lastStatuse o trecho da resposta da tentativa. - Verifique se os bytes brutos foram verificados com a chave correta para o esquema (a parte decodificada
whsec_parte para Webhooks Padrão, a string completa paraX-RTC-Signature). - Verifique o desvio de horário, os redirecionamentos e se o endpoint está habilitado.
Nunca registre o segredo de assinatura, solicitações brutas com assinatura ou credenciais dos participantes durante o diagnóstico de problemas.