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.
Points de terminaison
Section intitulée « Points de terminaison »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ètre | Signification |
|---|---|
| URL | Une 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. |
| Projet | Un projet, ou tous les projets de l’organisation (projectId: null). |
| Événements | Filtres : * 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). |
| Description | Votre 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.
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ès | Portée | Résultat |
|---|---|---|
GET /v1/webhooks/endpoints | webhooks:read | Points de terminaison, les plus récents en premier (?projectId, ?limit, ?cursor) |
POST /v1/webhooks/endpoints | webhooks:write | 201, le point de terminaison et sa clé de signature, affichés une seule fois |
GET /v1/webhooks/endpoints/{endpointId} | webhooks:read | Un point de terminaison, avec limit: { used, limit } |
PATCH /v1/webhooks/endpoints/{endpointId} | webhooks:write | Modifier url, description, events ou enabled |
DELETE /v1/webhooks/endpoints/{endpointId} | webhooks:write | { "deleted": true } |
POST /v1/webhooks/endpoints/{endpointId}/rotate-secret | webhooks:write | Un nouveau secret, affiché une seule fois (rotation) |
POST /v1/webhooks/endpoints/{endpointId}/test | webhooks:write | Envoie webhook.test maintenant et indique le résultat |
POST /v1/webhooks/endpoints/{endpointId}/replay | webhooks:write | 202, relecture groupée par plage horaire |
GET /v1/webhooks/deliveries | webhooks:read | Le journal des envois |
GET /v1/webhooks/deliveries/{deliveryId} | webhooks:read | Une seule transmission, à chaque tentative |
POST /v1/webhooks/deliveries/{deliveryId}/replay | webhooks:write | 202, renvoie cette livraison |
GET /v1/webhooks/event-types | webhooks:read | Le 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.
Signature des secrets
Section intitulée « Signature des secrets »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 :
- Effectuez la rotation et stockez la nouvelle clé secrète à côté de l’ancienne dans votre récepteur.
- Déployez un destinataire qui accepte l’un ou l’autre des secrets.
- 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.
Enveloppe d’événement
Section intitulée « Enveloppe d’événement »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.
Catalogue des événements
Section intitulée « Catalogue des événements »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énement | Statut | Envoyé lorsque |
|---|---|---|
room.created | actif | Une salle a été créée |
room.started | actif | Le premier participant a rejoint une salle |
room.empty | actif | Le dernier participant a quitté une salle ouverte |
room.idle_timeout | actif | Une salle ouverte n’a accueilli aucun participant pendant la période d’inactivité (data.idleSince, data.idleMinutes) |
room.locked | actif | Une salle a été verrouillée ou déverrouillée |
room.ended | actif | Une salle a été clôturée |
participant.joined | actif | Un participant a rejoint une salle |
participant.left | actif | Un participant a quitté une salle |
participant.updated | actif | Un 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_quality | prévu | Échantillonnage de la qualité de connexion (sur inscription) |
track.published | actif | Un participant a publié une piste |
track.unpublished | actif | Un participant a interrompu un enregistrement |
track.muted | actif | Un participant a mis une piste en sourdine, ou un animateur l’a mise en sourdine |
track.unmuted | actif | Une piste mise en sourdine a été réactivée |
recording.requested | actif | Un enregistrement a fait l’objet d’une demande |
recording.started | actif | La capture d’un enregistrement a commencé |
recording.stopped | actif | L’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.ready | actif | Chaque piste d’un enregistrement est stockée |
recording.failed | actif | Un enregistrement s’est terminé par un échec (les pistes capturées peuvent être conservées) |
recording.composite.ready | actif | Les fichiers vidéo et audio composites sont stockés |
recording.composite.failed | actif | Aucun fichier composite n’a pu être créé |
recording.delivered | actif | Un fichier d’enregistrement a été transféré vers votre propre espace de stockage |
recording.delivery_failed | actif | Un fichier d’enregistrement n’a pas pu être transféré vers votre propre espace de stockage |
recording.deleted | actif | Un 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.restored | actif | Un enregistrement a été restauré depuis la corbeille : data est { recordingId, roomId, restoredAt, by }, avec by customer ou admin |
recording.purged | actif | Un 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.queued | actif | La transcription d’un enregistrement a réservé ses minutes et est mise en file d’attente : data est { recordingId, roomId, reservedMinutes } (transcription) |
transcript.completed | actif | La 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.failed | actif | La 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.segment | prévu | Pas encore disponible pour les clients (sous-titrage en direct) |
captions.started | prévu | Pas encore disponible pour les clients |
captions.stopped | prévu | Pas encore disponible pour les clients |
whiteboard.created | actif | Un tableau blanc a été créé dans une salle |
whiteboard.archived | actif | Un tableau blanc a été archivé ou supprimé |
whiteboard.opened, whiteboard.closed, whiteboard.snapshot.ready | prévu | Activité sur le tableau blanc |
key.created | actif | Une cléAPI a été créée |
key.revoked | actif | Une cléAPI a été révoquée |
quota.warning | actif | Un 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.exhausted | actif | Un quota RTC est consommé (abonnement, période d’essai et packs) ; une fois par quota et par période de facturation |
subscription.changed | prévu | Modification de l’abonnement RTC (niveau, période d’essai, problème de paiement) |
webhook.test | actif | Un événement de test envoyé depuis la console ou le API |
webhook.endpoint_disabled | actif | L’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.ended | prévu | Diffusion 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.
Vérifier chaque requête
Section intitulée « Vérifier chaque requête »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: 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>| Schéma | Contenu signé | Clé HMAC-SHA256 | Signature |
|---|---|---|---|
| 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éfixe | X-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-Signaturene contient que le secret le plus récent. Un récepteur hérité qui conserve encore le secret précédent doit vérifierX-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èquewhsec_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 eventconst 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 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 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.
Répondre, dédupliquer et ordonner
Section intitulée « Répondre, dédupliquer et ordonner »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, journal de livraison et relecture
Section intitulée « Test, journal de livraison et relecture »- Test :
POST /v1/webhooks/endpoints/{endpointId}/testenvoie unwebhook.testévénement immédiatement et les réponses{ deliveryId, eventId, ok, status, latencyMs, error }. - Journal de livraison :
GET /v1/webhooks/deliveriesrépertorie les livraisons, les plus récentes en premier, avecstate(pending,retry,delivered,dead,cancelled),attempts,lastStatus,lastErroretlastLatencyMs. Filtrer avec?endpointId,?state,?typeet?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}/replayMettez à 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éponsesDELIVERY_IN_PROGRESS. - Rejeu en masse :
POST /v1/webhooks/endpoints/{endpointId}/replayavec{ "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éponses202 { "queued": n }.
Dépannage
Section intitulée « Dépannage »- Envoyez un événement de test et lisez son
statuseterror. - Lisez le journal de livraison
lastStatuset 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 pourX-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.