Pular para o conteúdo
Documentation

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.

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çãoSignificado
URLUma 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.
ProjetoUm projeto ou todos os projetos da organização (projectId: null).
EventosFiltros: * 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.
AtivadoOs 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çãoSeu 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.

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"] }'
Método e caminhoEscopoResultado
GET /v1/webhooks/endpointswebhooks:readPontos de extremidade, os mais recentes primeiro (?projectId, ?limit, ?cursor)
POST /v1/webhooks/endpointswebhooks:write201, o endpoint e seu segredo de assinatura, exibidos uma vez
GET /v1/webhooks/endpoints/{endpointId}webhooks:readUm endpoint, com limit: { used, limit }
PATCH /v1/webhooks/endpoints/{endpointId}webhooks:writeAlterar url, description, events ou enabled
DELETE /v1/webhooks/endpoints/{endpointId}webhooks:write{ "deleted": true }
POST /v1/webhooks/endpoints/{endpointId}/rotate-secretwebhooks:writeUm novo segredo, exibido uma vez (rotação)
POST /v1/webhooks/endpoints/{endpointId}/testwebhooks:writeEnvia webhook.test agora e informa o resultado
POST /v1/webhooks/endpoints/{endpointId}/replaywebhooks:write202, reprodução em lote por intervalo de tempo
GET /v1/webhooks/deliverieswebhooks:readO registro de entregas
GET /v1/webhooks/deliveries/{deliveryId}webhooks:readUma entrega, com todas as tentativas
POST /v1/webhooks/deliveries/{deliveryId}/replaywebhooks:write202, reenvia essa entrega
GET /v1/webhooks/event-typeswebhooks:readO 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.

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).

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:

  1. Faça a rotação e armazene o novo segredo ao lado do antigo em seu receptor.
  2. Implemente um receptor que aceite qualquer um dos segredos.
  3. 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.

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.

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.

EventoStatusEnviado quando
room.createdativoUma sala foi criada
room.startedativoO primeiro participante entrou em uma sala
room.emptyativoO último participante saiu de uma sala aberta
room.idle_timeoutativoUma sala aberta não teve participantes durante o período de inatividade (data.idleSince, data.idleMinutes)
room.lockedativoUma sala foi bloqueada ou desbloqueada
room.endedativoUma sala foi encerrada
participant.joinedativoUm participante entrou em uma sala
participant.leftativoUm participante saiu de uma sala
participant.updatedativoUm moderador alterou um participante (função, permissões, nome, metadados, silenciamento pelo anfitrião)
participant.connection_qualityplanejadoAmostragem da qualidade da conexão (opcional)
track.publishedativoUm participante publicou uma faixa
track.unpublishedativoUm participante interrompeu uma faixa
track.mutedativoUm participante silenciou uma faixa, ou um anfitrião a silenciou
track.unmutedativoUma faixa silenciada teve o silêncio desativado
recording.requestedativoFoi solicitada uma gravação
recording.startedativoA captura de uma gravação foi iniciada
recording.stoppedativoA 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.readyativoCada faixa de uma gravação é armazenada
recording.failedativoA gravação foi encerrada com falha (as faixas capturadas podem ser mantidas)
recording.composite.readyativoOs arquivos de vídeo e áudio compostos são armazenados
recording.composite.failedativoNão foi possível criar um arquivo composto
recording.deliveredativoUm arquivo de gravação foi entregue em seu próprio armazenamento
recording.delivery_failedativoNão foi possível entregar um arquivo de gravação no seu próprio armazenamento
recording.deletedativoUma 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.restoredativoUma gravação foi restaurada da Lixeira: data é { recordingId, roomId, restoredAt, by }, com by customer ou admin
recording.purgedativoUma 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.queuedativoA transcrição de uma gravação reservou seus minutos e está na fila: data é { recordingId, roomId, reservedMinutes } (transcrição)
transcript.completedativoA 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.failedativoA 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.segmentplanejadoAinda não disponível para os clientes (legendas em tempo real)
captions.startedplanejadoAinda não disponível para os clientes
captions.stoppedplanejadoAinda não disponível para os clientes
whiteboard.createdativoFoi criado um quadro branco em uma sala
whiteboard.archivedativoUm quadro branco foi arquivado ou excluído
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.readyplanejadoAtividade no quadro branco
key.createdativoFoi criada uma chaveAPI
key.revokedativoUma chaveAPI foi revogada
quota.warningativoUma 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.exhaustedativoUma cota de RTC é consumida (assinatura, período de teste e pacotes); uma vez por cota e por período de faturamento
subscription.changedplanejadoA assinatura do RTC foi alterada (plano, período de teste, problema de pagamento)
webhook.testativoUm evento de teste enviado a partir do console ou do API
webhook.endpoint_disabledativoUm 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.endedplanejadoStreaming 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.

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: 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>
EsquemaConteúdo assinadoChave HMAC-SHA256Assinatura
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 completowebhook-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_ prefixoX-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-Signature carrega apenas o segredo mais recente. Um receptor legado que ainda possua o segredo anterior deve verificar X-RTC-Signatures.
  • Bibliotecas padrão de Webhooks prontas para uso aceitam whsec_ segredos diretamente. Para um migrado rtc_… segredo, forneça à biblioteca whsec_ seguido pela codificação base64 dos bytes UTF-8 do segredo completo.

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 event
const 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 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 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.

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.

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: POST /v1/webhooks/endpoints/{endpointId}/test envia um webhook.test evento imediatamente e as respostas { deliveryId, eventId, ok, status, latencyMs, error }.
  • Registro de entrega: GET /v1/webhooks/deliveries lista as entregas, da mais recente à mais antiga, com state (pending, retry, delivered, dead, cancelled), attempts, lastStatus, lastError e lastLatencyMs. Filtre com ?endpointId, ?state, ?type e ?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}/replay Enfileira a entrega novamente. As repetições por entrega e por dia são limitadas (REPLAY_LIMIT, REPLAY_QUOTA); uma entrega sendo enviada responde DELIVERY_IN_PROGRESS.
  • Reprodução em massa: POST /v1/webhooks/endpoints/{endpointId}/replay com { "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 respostas 202 { "queued": n }.

  • Envie um evento de teste e leia seu status e error.
  • Leia o log de entrega lastStatus e 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 para X-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.