Aller au contenu
Documentation

Webhooks RTC

RTC envoie des événements concernant vos salles, vos participants, vos enregistrements et votre compte vers le webhook points de terminaison que vous enregistrez. Chaque point de terminaison dispose de sa propre URL, de ses filtres d’événements, de ses secrets de signature et de son journal de livraison. La livraison est au moins une fois: déduplication sur l’événement id avant d’agir.

Gérez les points de terminaison dans la console RTC sous Webhooks, via le API avec votre session de console, ou avec une cléAPI de projet qui dispose de la webhooks:read ou webhooks:write portée. Une clé de projet ne voit et ne gère que les points de terminaison de son propre projet.

ParamètreSignification
URLUne URL HTTPS publique sur le port 443. Les redirections ne sont pas suivies et les adresses privées ou réservées sont refusées, tant lors de l’enregistrement qu’à chaque tentative.
ProjetUn projet, ou tous les projets de l’organisation (projectId: null).
ÉvénementsFiltres : * pour chaque événement, une famille telle que recording.*, ou un type tel que room.ended. Un filtre ne correspondant à aucun type connu est refusé.
ActivéLes points de terminaison désactivés ne reçoivent rien. RTC désactive lui-même un point de terminaison lorsqu’il continue d’échouer (voir Nouvelles tentatives et désactivation automatique).
DescriptionVotre propre libellé, jusqu’à 500 caractères.

Le nombre de points de terminaison dépend de votre forfait. En créer un de plus que ce prévu par le forfait permet d’obtenir des réponses 409 avec le code WEBHOOK_ENDPOINT_LIMIT.

Fenêtre 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éthode et chemin d’accèsPortéeRésultat
GET /v1/webhooks/endpointswebhooks:readPoints de terminaison, les plus récents en premier (?projectId, ?limit, ?cursor)
POST /v1/webhooks/endpointswebhooks:write201, le point de terminaison et sa clé de signature, affichés une seule fois
GET /v1/webhooks/endpoints/{endpointId}webhooks:readUn point de terminaison, avec limit: { used, limit }
PATCH /v1/webhooks/endpoints/{endpointId}webhooks:writeModifier url, description, events ou enabled
DELETE /v1/webhooks/endpoints/{endpointId}webhooks:write{ "deleted": true }
POST /v1/webhooks/endpoints/{endpointId}/rotate-secretwebhooks:writeUn nouveau secret, affiché une seule fois (rotation)
POST /v1/webhooks/endpoints/{endpointId}/testwebhooks:writeEnvoie webhook.test maintenant et indique le résultat
POST /v1/webhooks/endpoints/{endpointId}/replaywebhooks:write202, relecture groupée par plage horaire
GET /v1/webhooks/deliverieswebhooks:readLe journal des envois
GET /v1/webhooks/deliveries/{deliveryId}webhooks:readUne seule transmission, à chaque tentative
POST /v1/webhooks/deliveries/{deliveryId}/replaywebhooks:write202, renvoie cette livraison
GET /v1/webhooks/event-typeswebhooks:readLe catalogue des événements

Un objet « endpoint » ne contient jamais de valeur secrète. Il répertorie chaque secret actif id, c’est bref prefix (par exemple whsec_Ab12), createdAt et, pendant une rotation, expiresAt. Il génère également un rapport status (active ou disabled), disabledReason (manual, failing, gone ou admin) et health (consecutiveFailures, lastSuccessAt, lastFailureAt, failingSince).

La priseCHAMPREP en charge d’un point de terminaison est désactivée (disabledReason: "admin") ne peut pas être activé ni faire l’objet d’un événement de test (WEBHOOK_ENDPOINT_ADMIN_DISABLED), et son URL ne peut pas être ajoutée à nouveau en tant que nouveau point de terminaison (WEBHOOK_URL_ADMIN_DISABLED). Contactez le service d’assistance.

Les listes renvoient un tableau JSON. Lorsqu’il existe plusieurs éléments, le X-Next-Cursor L’en-tête de réponse contient le curseur pour la page suivante ; renvoyez-le sous la forme ?cursor. ?limit accepte des valeurs comprises entre 1 et 200.

Les espaces de travail ayant configuré l’ancien webhook unique (PUT /v1/webhook) le conserver : il apparaît désormais comme un point de terminaison pour tous les projets et tous les événements, marqué legacy: true, et le /v1/webhook les routes continuent de fonctionner.

Le secret d’un nouveau point de terminaison se présente sous la forme whsec_ suivi d’un encodage base64. Il s’affiche une fois, dans la réponse à la requête de création ou de rotation, et RTC le stocke sous forme chiffrée. Enregistrez-le dans le gestionnaire de secrets de votre destinataire ; personne ne pourra vous le montrer à nouveau, y compris le service d’assistanceCHAMPREP. Si vous le perdez, effectuez une rotation du secret.

Ne collez jamais un secret de signature dans un chat, un ticket ou un journal. CHAMPREP AI L’assistant peut répertorier, créer, tester et rejouer des points de terminaison pour vous, mais il ne voit ni n’affiche jamais de secret : obtenez-en un dans la console (Webhooks, puis Roter le secret).

Remplacer une clé secrète sans interruption de service

Section intitulée « Remplacer une clé secrète sans interruption de service »

POST /v1/webhooks/endpoints/{endpointId}/rotate-secret avec { "overlapHours": 24 } crée une nouvelle clé secrète et maintient les précédentes valides pendant la période de chevauchement (de 0 à 72 heures, 24 par défaut). Pendant la période de chevauchement chaque livraison est signée avec chaque secret actif, ce qui permet aux destinataires de basculer à leur propre rythme :

  1. Effectuez la rotation et stockez la nouvelle clé secrète à côté de l’ancienne dans votre récepteur.
  2. Déployez un destinataire qui accepte l’un ou l’autre des secrets.
  3. Lorsque toutes les instances utilisent la nouvelle clé secrète, supprimez l’ancienne. La signature prend fin lorsque le chevauchement s’achève (previousSecretsExpireAt).

Utilisation overlapHours: 0 lorsqu’aucun destinataire n’utilise encore le point de terminaison, par exemple pour obtenir un secret pour un point de terminaison créé par l’assistant IA.

Les nouveaux points de terminaison utilisent la APIversion 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" }
}

Le point de terminaison hérité conserve l’enveloppe précédente, { id, type, createdAt, projectId, data }. Un point de terminaison apiVersion épingle la forme de la charge utile qu’il reçoit ; voir Gestion des versions.

Les identifiants ci-dessus sont donnés à titre d’exemple. Veuillez les traiter id sous la forme d’une chaîne opaque : certaines sont des UUID, d’autres sont dérivées, telles que recording-ready:<uuid>. projectId peut être absent pour un événement au niveau de l’organisation, et roomId est présent pour les événements de la salle.

GET /v1/webhooks/event-types renvoie la liste faisant autorité, chaque type étant accompagné d’une description et status: live (envoyée) ou planned (un nom réservé auquel vous êtes peut-être déjà abonné ; rien n’a encore été envoyé). Certains événements en direct ne sont envoyés que lorsque la fonctionnalité correspondante est activée pour votre espace de travail.

ÉvénementStatutEnvoyé lorsque
room.createdactifUne salle a été créée
room.startedactifLe premier participant a rejoint une salle
room.emptyactifLe dernier participant a quitté une salle ouverte
room.idle_timeoutactifUne salle ouverte n’a accueilli aucun participant pendant la période d’inactivité (data.idleSince, data.idleMinutes)
room.lockedactifUne salle a été verrouillée ou déverrouillée
room.endedactifUne salle a été clôturée
participant.joinedactifUn participant a rejoint une salle
participant.leftactifUn participant a quitté une salle
participant.updatedactifUn modérateur a modifié les paramètres d’un participant (rôle, autorisations, nom, métadonnées, mise en sourdine par l’hôte)
participant.connection_qualityprévuÉchantillonnage de la qualité de connexion (sur inscription)
track.publishedactifUn participant a publié une piste
track.unpublishedactifUn participant a interrompu un enregistrement
track.mutedactifUn participant a mis une piste en sourdine, ou un animateur l’a mise en sourdine
track.unmutedactifUne piste mise en sourdine a été réactivée
recording.requestedactifUn enregistrement a fait l’objet d’une demande
recording.startedactifLa capture d’un enregistrement a commencé
recording.stoppedactifL’enregistrement a été interrompu, une fois par enregistrement, avec le reason (requested, room_ended, max_duration, limit, tenant_inactive, shutdown, allowance lorsque les minutes d’enregistrement sont épuisées, billing_unavailable ou error)
recording.readyactifChaque piste d’un enregistrement est stockée
recording.failedactifUn enregistrement s’est terminé par un échec (les pistes capturées peuvent être conservées)
recording.composite.readyactifLes fichiers vidéo et audio composites sont stockés
recording.composite.failedactifAucun fichier composite n’a pu être créé
recording.deliveredactifUn fichier d’enregistrement a été transféré vers votre propre espace de stockage
recording.delivery_failedactifUn fichier d’enregistrement n’a pas pu être transféré vers votre propre espace de stockage
recording.deletedactifUn enregistrement a été envoyé dans la corbeille : data est { recordingId, roomId, reason, deletedAt, purgeAt }, avec reason customer (vous l’avez supprimé) ou retention (sa période de conservation a pris fin), et purgeAt lorsqu’il est supprimé automatiquement (30 jours plus tard ; cette durée est fixe lorsqu’il est envoyé dans la corbeille, null alors que la suppression automatique de la corbeille est désactivée). Il peut être restauré jusqu’à ce moment-là.
recording.restoredactifUn enregistrement a été restauré depuis la corbeille : data est { recordingId, roomId, restoredAt, by }, avec by customer ou admin
recording.purgedactifUn enregistrement a été supprimé définitivement de la corbeille : data est { recordingId, roomId, reason, purgedAt }, avec reason customer (vous l’avez supprimé de la corbeille), expired (supprimé automatiquement après 30 jours) ou admin (CHAMPREPassistance)
transcript.queuedactifLa transcription d’un enregistrement a réservé ses minutes et est mise en file d’attente : data est { recordingId, roomId, reservedMinutes } (transcription)
transcript.completedactifLa transcription d’un enregistrement est prête : data est { recordingId, roomId, segments, durationMs, billedMinutes, truncated }, avec truncated true lorsque le quota a été épuisé en raison d’une forte interférence. Jamais le texte.
transcript.failedactifLa transcription d’un enregistrement a échoué et rien n’a été facturé : data est { recordingId, roomId, error }, plus code (RTC_ALLOWANCE_EXHAUSTED, BILLING_UNAVAILABLE, CANCELLED ou RECORDING_LENGTH_UNKNOWN) et offers lorsque le quota est la raison
transcript.segmentprévuPas encore disponible pour les clients (sous-titrage en direct)
captions.startedprévuPas encore disponible pour les clients
captions.stoppedprévuPas encore disponible pour les clients
whiteboard.createdactifUn tableau blanc a été créé dans une salle
whiteboard.archivedactifUn tableau blanc a été archivé ou supprimé
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.readyprévuActivité sur le tableau blanc
key.createdactifUne cléAPI a été créée
key.revokedactifUne cléAPI a été révoquée
quota.warningactifUn quota RTC a dépassé un seuil d’alerte (80 %, sauf si CHAMPREP en définit d’autres) ; une fois par quota, par période de facturation et par pourcentage
quota.exhaustedactifUn quota RTC est consommé (abonnement, période d’essai et packs) ; une fois par quota et par période de facturation
subscription.changedprévuModification de l’abonnement RTC (niveau, période d’essai, problème de paiement)
webhook.testactifUn événement de test envoyé depuis la console ou le API
webhook.endpoint_disabledactifL’un de vos points de terminaison a été désactivé après un échec ou une réponse 410: data est { endpointId, url, host, reason }. url correspond uniquement au schéma, à l’hôte et au chemin d’accès, jamais à la chaîne de requête ; host correspond à l’hôte seul ; reason est failing ou gone.
egress.started, egress.ended, ingress.started, ingress.endedprévuDiffusion en continu et ingestion (non encore disponible)

Les événements contiennent des identifiants, et non des noms d’affichage, des jetons, des adresses IP ou des médias. Réconciliez les états importants avec le API plutôt que de vous fier à un seul événement.

Chaque envoi comporte deux schémas de signature indépendants. Vérifiez un parmi ceux-ci, sur le octets exacts du corps brut de la requête, avant d’analyser le JSON ou d’effectuer toute action. Ne jamais analyser ni resérialiser le corps à des fins de vérification.

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>
SchémaContenu signéClé HMAC-SHA256Signature
Webhooks standard (recommandé)<webhook-id>.<webhook-timestamp>.<raw body>whsec_… secrets : la partie décodée en Base64 après le whsec_ préfixe. Anciens rtc_… secrets : les octets UTF-8 du secret dans son intégralitéwebhook-signature: séparés par des espaces v1,<base64>, un par secret actif
RTC (hérité)<X-RTC-Timestamp>.<raw body>Les octets UTF-8 de la chaîne secrète complète, y compris tout whsec_ ou rtc_ préfixeX-RTC-Signature: v1=<hex> pour le secret le plus récent ; X-RTC-Signatures: chaque secret actif, séparés par des espaces

Pour les deux schémas :

  • Rejetez tout horodatage dont l’écart par rapport à votre horloge est supérieur à cinq minutes.
  • Comparez les signatures en temps constant, et acceptez la requête lorsque n’importe quel La signature répertoriée correspond à l’un de vos secrets.
  • Au cours d’une Chevauchement de rotation, X-RTC-Signature ne contient que le secret le plus récent. Un récepteur hérité qui conserve encore le secret précédent doit vérifier X-RTC-Signatures.
  • Les bibliothèques de webhooks standard prêtes à l’emploi acceptent whsec_ secrets directement. Pour un point de terminaison migré rtc_… secret, fournissez à la bibliothèque whsec_ suivi de l’ encodage base64 de l’ensemble des octets UTF-8 du secret.

Le Exemple de vérification implémente les deux schémas sans dépendances :

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.

Au cours d’une rotation, appelez le vérificateur une fois par secret que vous détenez.

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 doit être un mappage insensible à la casse, tel que request.headers dans Flask, Django ou Starlette, et raw_body le corps non analysé (request.get_data() Dans Flask, request.body Dans Django, await request.body() dans Starlette).

Ces exemples constituent des conseils d’intégration du récepteur, et non des serveurs complets. Définissez une limite pour le corps de la requête, gérez les données JSON mal formées et validez l’enveloppe.

Renvoyez un 2xx Répondez rapidement après avoir accepté de manière durable un événement vérifié, et effectuez les tâches plus longues de manière asynchrone. Chaque tentative expire au bout de 5 secondes. Tout autre statut, une redirection ou un délai d’expiration est considéré comme une tentative échouée.

Persister event.id de manière atomique et traitez chaque événement une seule fois ; un ensemble en mémoire ne suffit pas en cas de redémarrage ou de présence de plusieurs instances de récepteur. La vérification de l’horodatage à elle seule n’empêche pas une relecture dans la fenêtre acceptée. L’ordre n’est pas garanti : utilisez les horodatages dans data et le API pour résoudre l’état actuel.

Nouvelles tentatives et désactivation automatique

Section intitulée « Nouvelles tentatives et désactivation automatique »

Une livraison ayant échoué fait l’objet de nouvelles tentatives avec un recul exponentiel et une variation de délai pendant environ 24 heures (12 tentatives), puis est marquée dead. Chaque tentative est signée à nouveau à l’aide des secrets actifs du point de terminaison et d’un nouvel horodatage.

Chaque tentative expire au bout de 5 secondes. RTC désactive un point de terminaison (disabledReason: "failing") lorsque l’une des deux conditions suivantes est remplie :

  • il a dépassé le délai d’expiration 25 fois d’affilée et qu’il est également en état d’échec depuis au moins 1 heure ;
  • il a connu des défaillances en continu pendant 24 heures (CHAMPREPpeut définir une autre durée).

Il le désactive immédiatement ("gone") lorsqu’il répond 410 Gone. Le propriétaire de l’organisation est averti, et un webhook.endpoint_disabled L’événement est envoyé à vos autres points de terminaison. Corrigez le récepteur, puis réactivez le point de terminaison (PATCH avec { "enabled": true }) ; l’activation efface son état d’échec.

  • Test : POST /v1/webhooks/endpoints/{endpointId}/test envoie un webhook.test événement immédiatement et les réponses { deliveryId, eventId, ok, status, latencyMs, error }.
  • Journal de livraison : GET /v1/webhooks/deliveries répertorie les livraisons, les plus récentes en premier, avec state (pending, retry, delivered, dead, cancelled), attempts, lastStatus, lastError et lastLatencyMs. Filtrer avec ?endpointId, ?state, ?type et ?eventId. Une livraison (GET /v1/webhooks/deliveries/{deliveryId}) ajoute chaque tentative avec son statut, sa latence et le premier kilo-octet de la réponse de votre destinataire, ainsi que l’ événement lui-même. Le journal est conservé pendant une durée limitée.
  • Première relecture : POST /v1/webhooks/deliveries/{deliveryId}/replay Mettez à nouveau la livraison en file d’attente. Les relectures par livraison et par jour sont limitées (REPLAY_LIMIT, REPLAY_QUOTA) ; une livraison en cours d’envoi renvoie des réponses DELIVERY_IN_PROGRESS.
  • Rejeu en masse : POST /v1/webhooks/endpoints/{endpointId}/replay avec { "from": "2026-11-08T00:00:00Z", "to": "2026-11-08T06:00:00Z", "types": ["recording.*"], "onlyFailed": true } met en file d’attente les événements correspondants à cette plage horaire pour le point de terminaison, au maximum 1 000 par requête, ainsi que les réponses 202 { "queued": n }.

  • Envoyez un événement de test et lisez son status et error.
  • Lisez le journal de livraison lastStatus et l’extrait de la réponse de la tentative.
  • Vérifiez que vous validez les octets bruts à l’aide de la clé appropriée pour le schéma (la partie décodée whsec_ partie pour les webhooks standard, la chaîne complète pour X-RTC-Signature).
  • Vérifiez le décalage horaire, les redirections et assurez-vous que le point de terminaison est activé.

N’enregistrez jamais le secret de signature, les requêtes brutes comportant une signature ou les identifiants des participants lors du dépannage.