אינטגרציה ו-API

Utiliser les Webhooks Kavkom

ספטמבר 25, 2026
10:00 am

Un webhook permet à une application d’envoyer automatiquement des informations à une autre lorsqu’un événement se produit.

Avec Kavkom, les événements téléphoniques que vous sélectionnez sont transmis vers l’URL de votre choix à l’aide de requêtes HTTP POST contenant des données au format JSON.

Vous pouvez notamment recevoir des informations :

pendant un appel entrant ;
pendant un appel sortant ;
après la fin d’un appel grâce au CDR (Call Detail Record).

Principe. Votre application n’a pas besoin d’interroger régulièrement Kavkom pour rechercher de nouveaux événements. Kavkom envoie automatiquement les informations sélectionnées vers votre endpoint.

Exemples d’utilisation

📞

Activités d’appels

Transmettez les informations relatives aux appels entrants, sortants ou terminés vers votre CRM ou votre application métier.

🔴

Suivi d’un appel en direct

Recevez les changements d’état d’un appel pendant son déroulement et utilisez-les dans vos interfaces ou automatisations.

📵

Appels non aboutis

Exploitez le résultat final d’un appel pour créer une tâche, générer une alerte ou déclencher une relance dans un outil externe.

🎙️

Enregistrements d’appels

Lorsqu’un enregistrement est disponible, son URL peut être transmise dans le CDR à l’aide du champ recording_url.

📊

Statistiques et reporting

Envoyez les données des appels terminés vers vos outils d’analyse, vos tableaux de bord ou vos solutions de Business Intelligence.

⚙️

Automatisations métiers

Déclenchez vos propres workflows à partir des événements et données d’appels reçus depuis Kavkom.

Enregistrements. Le webhook ne transmet pas le fichier audio de l’enregistrement. Il transmet uniquement son URL lorsqu’elle est disponible.

Configurer un webhook Kavkom

Avant de commencer, assurez-vous de disposer d’un endpoint capable :

de recevoir des requêtes HTTP POST ;
d’interpréter les données au format JSON ;
de retourner une réponse HTTP.

Connectez-vous à Kavkom avec un compte disposant des autorisations nécessaires, puis rendez-vous dans :

Réglages avancés → Intégrations → Webhook → Installer

La fenêtre de configuration regroupe les six zones présentées ci-dessous.

Vue d'ensemble de la fenêtre de configuration du Webhook Kavkom avec repères numérotés

1. Indiquer l’Endpoint

Dans le champ Endpoint, saisissez l’URL vers laquelle Kavkom doit envoyer les requêtes.

Configuration de l'endpoint du Webhook Kavkom et bouton Test

https://example.com/webhooks/kavkom

Tester l’Endpoint

Après avoir renseigné l’adresse, cliquez sur le bouton Test.

Kavkom envoie alors une requête vide vers l’endpoint et attend une réponse du serveur destinataire.

À quoi sert le test ?
Il permet de vérifier que le serveur destinataire est joignable avant d’activer l’envoi des événements téléphoniques.

Le test ne simule pas un appel réel et ne contient pas les données d’un appel.

2. Configurer les Headers

La section Headers permet d’ajouter des informations aux en-têtes HTTP envoyés avec les requêtes.

Configuration des headers du Webhook Kavkom

Chaque header est constitué d’une paire Key / Value. Ils peuvent notamment servir à transmettre les informations nécessaires à l’authentification de votre endpoint.

Key: Authorization
Value: Bearer votre_token

Sécurité. Évitez de placer des informations sensibles directement dans l’URL. Utilisez de préférence les headers pour transmettre vos informations d’authentification.

3. Ajouter des Variables

La section Variables permet d’ajouter des paramètres personnalisés sous forme de paires Key / Value.

Configuration des variables du Webhook Kavkom

Ces variables peuvent servir à transmettre des informations complémentaires propres à votre intégration, par exemple un identifiant d’environnement, de compte ou de traitement.

4. Choisir les appels à transmettre

Dans la section What calls should be pushed?, sélectionnez les catégories d’événements que Kavkom doit envoyer vers votre endpoint.

Choix des appels à transmettre par le Webhook Kavkom

Vous pouvez activer plusieurs catégories simultanément.

5. Configurer le mapping des données

Kavkom propose deux mappings indépendants :

Mapping for life calls pour les appels en direct ;
Mapping for CDR pour les appels terminés.

Si aucun mapping n’est configuré : Kavkom transmet l’ensemble des données disponibles pour le type d’événement concerné.

Si vous configurez un mapping, vous pouvez associer une clé de votre choix au champ Kavkom attendu par votre application.

Mapping for life calls

Mapping des appels en direct dans le Webhook Kavkom

Ce mapping concerne les événements des appels entrants et sortants en direct.

Mapping for CDR

Ce mapping concerne les données finales envoyées après la fin de l’appel.

Données disponibles pour les appels en direct

Champ	Description
`domain_uuid`	Identifiant du domaine Kavkom.
`callId`	Identifiant de l’appel en cours.
`number`	Numéro associé à l’événement d’appel.
`extension`	Extension concernée par l’appel.
`direction`	Direction de l’appel.
`state`	État de l’appel au moment où l’événement est envoyé.

À quoi sert le champ `state` ?

Le champ state permet à votre application de suivre l’évolution d’un appel et d’adapter son traitement selon les événements reçus.

Important. Les événements en direct décrivent l’état d’un appel. Ils ne permettent pas de savoir si un utilisateur Kavkom est actuellement connecté ou déconnecté et ne constituent pas un statut global de disponibilité de l’utilisateur.

Données disponibles pour les appels terminés

Le Mapping for CDR permet d’exploiter les informations disponibles après la fin d’un appel.

Champ	Description
`xml_cdr_uuid`	Identifiant unique du CDR.
`domain_name`	Domaine associé à l’appel.
`direction`	Direction de l’appel.
`status`	Statut final de l’appel.
`duration`	Durée totale de l’appel.
`billsec`	Durée de communication comptabilisée.
`outside_number`	Numéro externe associé à l’appel.
`destination_number`	Numéro de destination.
`referenced_did`	DID référencé pour l’appel.
`referenced_extension`	Extension référencée pour l’appel.
`caller_id_number`	Numéro utilisé comme identifiant de l’appelant.
`caller_destination`	Destination associée à l’appel.
`start_epoch`	Heure de début au format Epoch.
`start_stamp`	Date et heure de début.
`end_epoch`	Heure de fin au format Epoch.
`end_stamp`	Date et heure de fin.
`answer_stamp`	Date et heure de réponse.
`answer_epoch`	Heure de réponse au format Epoch.
`recording_url`	URL de l’enregistrement lorsque celui-ci est disponible.

Selon le type d’appel et son déroulement, certaines données peuvent ne pas être renseignées.

Enregistrement d’appel

Lorsqu’un appel a été enregistré et qu’une URL est disponible, elle peut être transmise à votre application dans le champ :

recording_url

Le fichier audio n’est pas envoyé dans le webhook.
Kavkom transmet uniquement l’URL de l’enregistrement.

Votre application peut ensuite décider comment exploiter cette URL : l’associer à une activité CRM, l’utiliser dans une application métier, déclencher un traitement externe ou l’intégrer à votre propre processus d’archivage.

Appels en direct et CDR : quelle différence ?

Appels en direct	CDR
Envoyés pendant le déroulement de l’appel.	Envoyé après la fin de l’appel.
Décrivent l’état courant de l’appel.	Contient les informations finales disponibles.
Permettent de suivre l’évolution de l’appel.	Permet d’exploiter le résultat de l’appel.
`callId`, `extension`, `direction`, `state`…	`status`, `duration`, `billsec`, horodatages, `recording_url`…

Les appels en direct et les CDR peuvent être activés simultanément sur le même webhook.

Exemple d’utilisation avec un CRM

Un appel entrant est reçu sur Kavkom.
Kavkom envoie un événement vers votre endpoint.
Votre application récupère le numéro et les informations disponibles.
Le CRM peut rechercher le contact correspondant et créer ou mettre à jour une activité.
Les événements suivants permettent de suivre l’évolution de l’appel.
Lorsque l’appel se termine, Kavkom envoie le CDR.
Votre application peut enregistrer le statut, la durée et les autres informations finales disponibles.
Si un enregistrement existe, son URL peut être associée à l’activité.

Bonnes pratiques

Utilisez HTTPS

Utilisez de préférence un endpoint HTTPS pour sécuriser les échanges entre Kavkom et votre serveur.

Authentifiez votre endpoint

Utilisez les headers pour transmettre les informations nécessaires à l’authentification.

Validez les données reçues

Vérifiez les valeurs reçues avant de les transmettre à vos systèmes métiers.

Prévoyez les champs vides

Certaines informations peuvent ne pas être renseignées selon le scénario d’appel.

Conservez les identifiants

Les identifiants d’appels facilitent la corrélation des événements et les diagnostics.

Répondez rapidement

Votre serveur doit retourner une réponse HTTP lorsque le webhook a correctement été reçu.

À retenir

Les webhooks Kavkom permettent de connecter les événements de votre téléphonie à vos applications externes sans avoir à interroger continuellement le système.

événements des appels entrants en direct ;
événements des appels sortants en direct ;
CDR des appels terminés ;
URL d’un enregistrement lorsqu’elle est disponible.

Le mapping permet ensuite de sélectionner et d’adapter les données transmises aux besoins de votre CRM, de votre logiciel métier ou de votre application.