Comment utiliser, paramétrer et 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_country": "FRA",
"calling_number": "0033612345678",
"calling_type": "mobile",
"channel_name": "Google Ads",
"channel_type": "googleads",
"date": "2023-08-30 13:57:30",
"duration": 43,
"end_status": "completed",
"events": [
{
"date": "2023-08-30 13:57:30",
"name": "call:in",
"value": null
},
{
"date": "2023-08-30 13:57:31",
"name": "call:out",
"value": "0033687654321"
},
{
"date": "2023-08-30 13:57:33",
"name": "call:ringing",
"value": "0033687654321"
},
{
"date": "2023-08-30 13:57:48",
"name": "call:answered",
"value": "0033687654321"
},
{
"date": "2023-08-30 13:58:13",
"name": "call:completed",
"value": "no-answer"
}
],
"firsttime_caller": true,
"flow_status": "completed",
"google_ads_extension": null,
"missed": false,
"number_id": "num-18dd0fdb-7f21-4999-9335-a5d50d8c716e",
"pool_id": "pul-c8c7912c-5e3e-4b19-8769-4daadea66dea",
"recipient_number": "0033687654321",
"tracked_country": "FRA",
"tracked_number": "0033412345678",
"tracked_type": "geographic",
"voice_duration": 43,
"visitor": {
"condition_name": "Google Ads",
"condition_type": "google_ads",
"custom_cookies": [],
"custom_local_storage": [],
"custom_params": [],
"ga": "GA1.1.12345678.87654321",
"gclid": "EAIaIQobChER4_LZnaeJ4gIV3EdFFh2raA5aEAAYAiAAEgKyCF3_BwE",
"msclkid": null,
"utm": [
{
"key": "utm_source",
"value": "googleads"
}
],
"valuetrack": [],
"3rdparty": []
}
},
"event": "test"
}
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 Magnetis. Ce n’est pas obligatoire, mais cela offre un moyen de vérification supplémentaire.
Vérification de la signature de la requête
Magnetis inclut un en-tête HTTP supplémentaire avec les données POST envoyées par le Webhook, la signature X-CALLTRACKING-SIGNATURE, qui contiendra la signature de la requête. 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 de la signature X_CALLTRACKING_SIGNATURE.
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
Dans votre code qui reçoit les requêtes webhook (fichier défini en tant qu'url de destination / Endpoint) :
- 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 pour générer une signature binaire.
- Codez en Base64 la signature binaire
- Comparez la signature binaire que vous avez généré à la signature fournie dans l’en-tête http de la signature X-CALLTRACKING-SIGNATURE.
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.
Related Articles
Comment commander un numéro tracké et le paramétrer ?
Pour commander et paramétrer un numéro tracké, vous devez d'abord avoir un compte de Call-tracking. Découvrez comment créer un compte Magnetis. Commander un numéro tracké Lorsque vous êtes sur votre compte Magnetis, vous pouvez commander un nouveau ...Comment paramétrer mes rapports statistiques journalier, hebdomadaire et mensuels ?
Les rapports vous permettent de recevoir les données du Call-tracking directement sur votre boîte mail et/ou celles de vos clients. Pour chaque rapport vous avez le choix entre trois fréquences de réception : Journalière, Hebdomadaire, Mensuelle. ...Comment ajouter, modifier ou supprimer un destinataire d'appels ?
Le destinataire correspond à votre numéro d'origine, celui qui réceptionnera les appels entrants. Il s'agit donc du numéro vers lequel les appels passés sur les numéros trackés seront redirigés. Vous pouvez paramétrer plusieurs destinataires dans ...Comment supprimer un numéro tracké ?
Avant la suppression d'un numéro tracké et par mesure de sécurité, vous devez retirer le destinataire du numéro avant de le supprimer. Voici la marche à suivre : Connectez-vous à votre compte Magnetis et dirigez-vous dans l'espace "Numéros trackés". ...Comment créer un compte Magnetis ?
La création de compte est gratuite, elle vous permet d'obtenir vos numéros trackés directement en ligne. Un gestionnaire de compte vous sera affecté pour répondre à vos questions et vous aider à optimiser votre compte. 1. Connectez-vous sur notre ...