Comment utiliser, paramétrer, tester un webhook?
Pourquoi utiliser les webhooks Magnétis ?
Les webhooks permettent de lancer une action de façon automatique (vers votre CRM par exemple) lorsqu'un appel est reçu sur vos numéros trackés pour connecter vos outils au call-tracking. Contrairement à l'API qui vous permet d'aller chercher les informations et d'interagir avec l'interface Magnétis, le webhook est géré par nos soins et vous permet d'être notifié à chaque fois qu'un évènement se produit sur vos numéros trackés.
Si vous souhaitez réaliser une ou plusieurs actions suite à la réception d'un appel sur vos numéros trackés, vous pouvez également explorer les nombreuses possibilités offertes par notre intégration Zapier.
Paramétrage du webhook
Vous pouvez créer des flux webhooks pour l'ensemble de votre entreprise, agence ou réseaux de points de vente dans la partie Organisation de l'interface Magnétis, pour des réseaux ou comptes spécifiques.
Pour cela, une fois connecté au compte ou réseau souhaité, rendez-vous dans API & connecteurs > Webhooks.
Pour ajouter un nouveau webhook, cliquez sur "Ajouter un endpoint", puis complétez le formulaire suivant :
Titre : un titre explicite afin d'identifier le webhook
Endpoint : Adresse URL de récolte de l'évènement envoyé par le webhook. C'est ce endpoint qui contiendra le code permettant la récupération et l'intégration des données dans vos propres outils
Evènements : Evènement générateur de l'envoi des données vers votre endpoint URL. Les évènements disponibles sont :
Call > À la fin d'un appel [call:completed]
Call > Lorsqu'un appel est manqué [call:missed]
Call > Lorsqu'un appel sonne [call:ringing]
Email > Lorsqu'un email est reçu [email:received]
Lead > Lorsqu'un lead est créé [lead:created]
Customiser cet évènement [optionnel] : vous pouvez sélectionner un groupe de comptes ou de numéros pour lesquels exécuter ce webhook et définir des conditions de durée d'appel en secondes pour son déclenchement :
Remontée des évènements : statut de votre webhook
Format des données envoyées
Pour exemple, voici un exemple de format de données envoyé pour un webhook de type call:completed
"data": {
"id": "call-0c5ac87f-6d8b-4e94-9ce2-f4773bced2f5",
"account": { "id": "acc-efd1bbeb-afbb-4895-a6d5-40a13558af49", "name": "My account" },
"calling_number": "0033612345678",
"duration": 43,
"end_status": "completed",
"missed": false,
"tracked_number": "0033412345678"
},
"event": "test"
Documentation express : Le modèle de données détaillé est disponible dans la documentation suivante : https://docs.magnetis.io/#calls-GETcalls--id-
Tester le webhook
Dans le détail d'un webhook, la zone de droite vous permet de tester le webhook et d'envoyer à votre endpoint des données d'exemple. Vous obtiendrez le retour de votre endpoint en statut et en data.
Vous pouvez tester les modèles de données pour :
la ressource CALL : correspond à un appel entrant
la ressource EMAIL : pour les emails trackés reçus
la ressource LEAD : lors de la création d'un lead suite à la réception d'un appel entrant ou d'un email tracké
Les 10 dernières tentatives sont affichées en historique :
Signature des requêtes et sécurisation des échanges
Magnétis signe les requêtes de webhook pour que vous puissiez (optionnellement) vérifier que ces requêtes sont générées par Magnétis et non pas par un tiers qui prétend être Magnétis. Si votre application contient des données sensibles, vous vous assurerez ainsi que les requêtes proviennent bien de Magnétis.
Vérification de la signature de la requête
Magnétis inclut un en-tête HTTP supplémentaire avec les données POST envoyées par le Webhook, la signature X-CALLTRACKING-SIGNATURE. Pour vérifier une requête webhook, il faut générer une signature qui utilise la même clé que celle de Magnétis et la comparer à la valeur de l’en-tête.
Obtenir votre clé de signature Webhook
Quand vous créez un webhook, une clé est automatiquement générée. Vous pouvez voir et réinitialiser la clé depuis la page Webhooks dans le détail du webhook.
Générer une signature
Créez une chaîne avec l’URL du webhook, exactement de la même manière que vous l’avez entrée dans l'interface.
Triez les variables POST de la requête par clé et par ordre alphabétique.
Ajoutez chaque clé et chaque valeur des variables POST à la chaîne URL
Ajustez la chaîne obtenue avec HMAC-SHA1, en utilisant votre clé de signature webhook.
Codez en Base64 la signature binaire.
Comparez la signature générée à celle fournie dans l'en-tête X-CALLTRACKING-SIGNATURE.
Astuce : Notre équipe support est disponible pour vous accompagner dans l'intégration des webhooks et vous fournir des exemples de collecte des données et de vérification de signature.