Pourquoi utiliser les webhooks Magnétis?
Les webhooks permettent de lancer une action de façon automatique (vers votre CRM par exemple) lorsque qu'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
Le paramétrage du webhook se fait directement via l'interface dans API & Connecteurs > Webhook.
Dans cette zone, vous pourrez définir les paramètres :
- Le titre du webhook
- Le endpoint qui correspond au point de terminaison qui héberge votre script qui récupèrera et traitera les données envoyées (https recommandé)
- Le type d'évènement à envoyer via le webhook. 4 types d'évènements sont disponibles dans les webhook :
- Tous les appels
- Les appels manqués
- Les conversions du module visiteur (disponible si le module visiteur est actif)
- Les SMS reçus (pour les numéros Premium mobile)
- Le statut du webhook
Sur le coté droit, vous disposez de fonctionnalités afin de vérifier la réponse du endpoint que vous avez défini, envoyer un évènement de test et réinitialiser la signature (dans le cas où vous utilisez la signature des requêtes)
Le webhook envoie les évènements en POST dans un tableau vers le point de terminaison mentionné dans l'interface.
La structure des variables envoyées est :
- ["calltracking_event":["idcall":"1234567","accountname":"Calltracking Agence","date":"2019-09-01 10:00:00","trackednumber":"0033988776655","channelname":"Site Internet","callingNumber":"0033655443322","duration":"120"]]
Détails des variables en paramétrage initial [Par défaut]:
- calltracking_event : contient le tableau avec les variables de l'évènement d'appel
- idcall : numéro unique Magnétis d'identification de l'appel
- accountname : nom du compte dans lequel se trouve le numéro tracké appelé
- date : date de réception de l'appel
- trackednumber : numéro tracké Magnétis composé par l'appelant
- channelname : nom du canal/support de call-tracking
- callingNumber : numéro de l'appelant (peut être Anonymous si appel masqué)
- duration : durée de l'appel en secondes
Données renvoyées en parcours visiteur avec les ID de tracking
- Données initales +
- trackingids
- cid : ID Google Analytics
- gclid : ID de tracking Google Ads
- msclkid : ID de tracking Bing Ads
- others : variables UTM présentent dans l'URL de la landing page (par exemple "utm_campaign": "campaign","utm_source": "google",...)
- valuetrack : variables valuetrack présentent dans l'URL de la landing page (par exemple "campaignid": "1234567890","adgroupid": "0987654321",...)
Données renvoyées en suivi des extensions d'annonces
- Données initiales +
- google_call_extension":
- "campaignId": "1234567890",
- "campaignName": "My campaign",
- "AdgroupId": "0987654321",
- "AdgroupName": "My adgroup"
Tester le 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.
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 souhaiterez surement être sûr que les requêtes proviennent 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 une entê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’entê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éinitialiiser la clé depuis la page Webhooks dans votre compte, dans les paramètres détaillés.
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’entête http de la signature X-CALLTRACKING-SIGNATURE.
Exemple en PHP
- if(isset($_POST['form_data']))
- {
- $XCALLTRACKINGSignature = $_SERVER['HTTP_X_CALLTRACKING_SIGNATURE'];
- $params = $_POST;
- $webhook_key = "qChJkeBjdeXXXXXXXXXXXXXTlBL";
- $url = "http://your_domain.com/your_endpoin_tfile.php";
-
- $signed_data = $url;
- ksort($params);
-
- foreach ($params as $key => $value) {
- if(is_array($value) && !empty($value))
- {
- foreach ($value as $subkey => $subvalue)
- {
- $signedData .= $subkey;
- $signedData .= $subvalue;
- }
- }
- else
- {
- $signedData .= $key;
- $signedData .= $value;
- }
- }
- $generateSignature = base64_encode(hash_hmac('sha1', $signedData, $webhook_key, true)) ;
-
- if($generateSignature==$XCALLTRACKINGSignature)
- {
- print_r($_POST['form_data']);
- }
- }