Comment utiliser, paramétrer, tester un webhook?

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) 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 :
  1. Le titre du webhook
  2. 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é)
  3. Le type d'évènement à envoyer via le webhook. 4 types d'évènements sont disponibles dans les webhook : 
    1. Tous les appels
    2. Les appels manqués
    3. Les conversions du module visiteur (disponible si le module visiteur est actif)
    4. Les SMS reçus (pour les numéros Premium mobile)
  4. 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)

Format des données envoyées

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 :
  1. ["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]:
  1. calltracking_event : contient le tableau avec les variables de l'évènement d'appel
  2. idcall : numéro unique Magnétis d'identification de l'appel
  3. accountname : nom du compte dans lequel se trouve le numéro tracké appelé
  4. date : date de réception de l'appel
  5. trackednumber : numéro tracké Magnétis composé par l'appelant
  6. channelname : nom du canal/support de call-tracking
  7. callingNumber : numéro de l'appelant (peut être Anonymous si appel masqué)
  8. duration : durée de l'appel en secondes

Données renvoyées en parcours visiteur avec les ID de tracking
  1. Données initales +
  2. trackingids
    1. cid : ID Google Analytics
    2. gclid : ID de tracking Google Ads
    3. msclkid : ID de tracking Bing Ads
    4. others : variables UTM présentent dans l'URL de la landing page (par exemple "utm_campaign": "campaign","utm_source": "google",...)
    5. 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
  1. Données initiales +
  2. google_call_extension":
    1. "campaignId": "1234567890",
    2. "campaignName": "My campaign",
    3. "AdgroupId": "0987654321",
    4. "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):
  1. 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.
  2. Triez les variables POST de la requête par clé et par ordre alphabétique.
  3. Ajoutez chaque clé et chaque valeur des variables POST à la chaîne URL
  4. Ajustez la chaîne obtenue avec HMAC-SHA1, en utilisant votre clé de signature webhook pour générer une signature binaire.
  5. Codez en Base64 la signature binaire
  6. 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
  1. if(isset($_POST['form_data']))
  2. {
  3.     $XCALLTRACKINGSignature = $_SERVER['HTTP_X_CALLTRACKING_SIGNATURE'];

  4. $params = $_POST;
  5. $webhook_key = "qChJkeBjdeXXXXXXXXXXXXXTlBL";
  6. $url = "http://your_domain.com/your_endpoin_tfile.php";

  7. $signed_data = $url;
  8. ksort($params);

  9. foreach ($params as $key => $value) {
  10. if(is_array($value) && !empty($value))
  11. {
  12. foreach ($value as $subkey => $subvalue) 
  13. {
  14. $signedData .= $subkey;
  15. $signedData .= $subvalue;
  16. }
  17. }
  18. else
  19. {
  20. $signedData .= $key;
  21. $signedData .= $value;
  22. }
  23. }

  24. $generateSignature = base64_encode(hash_hmac('sha1', $signedData, $webhook_key, true)) ;

  25. if($generateSignature==$XCALLTRACKINGSignature)
  26. {
  27.          print_r($_POST['form_data']);
  28.     }
  29. }

    • Related Articles

    • Comment commander un numéro tracké et le paramétrer ?

      Commander un numéro tracké Vous devez avoir créé un compte Magnétis pour créer un numéro. cf article "Comment créer un compte Magnétis". 1. Dans votre interface, cliquez sur "Numéros trackés". Vous avez alors deux options : Choisir une architecture ...
    • Comment créer un compte Magnétis?

      La création de compte est gratuite. Elle vous permet d'obtenir vos numéros trackés directement en ligne. Un gestionnaire de compte est affecté à chaque client 1. Connectez-vous sur notre site web https://www.magnetis.fr/ puis cliquez sur "Créer un ...
    • Comment paramétrer du Call-tracking pour une campagne d'emailing ?

      Paramétrer du call-tracking pour une campagne d’emailing Lorsque vous utilisez le call-tracking, vous pouvez le faire pour une campagne d’emailing. Pour cela, deux options complémentaires s’offrent à vous. Il s’agit des 2 points de contact à partir ...
    • Comment modifier un indicatif d'appels ?

      Modifier un indicatif d’appels Lors de l’utilisation du call-tracking, vous pouvez être amené(e) à vouloir modifier l’indicatif d’un numéro tracké. Pour cela, plusieurs possibilités s’offrent à vous. Vous pouvez décider de modifier votre indicatif ...
    • Comment tester la rotation des numéros sur mon site internet ?

      Tester la rotation des numéros sur mon site internet Après avoir paramétré et installé votre module de call-tracking, il est possible de tester la rotation des numéros sur votre site internet. C’est-à-dire vérifier que le module installé permet bien ...