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","cid":"GA1.2.1669789410.1567091110"]]
Détails des variables :
  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
  9. cid : ID Google Analytics (uniquement en module visiteur)
  10. visitorevents : 

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 ajouter, modifier et supprimer un destinataire d’appel (pays, fixe, mobile)

      Un destinataire correspond au numéro d'origine de réception des 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 votre compte et ...
    • Comment utiliser l’API de call-tracking

      L'API Magnetis vous permet d'intégrer le call-tracking dans vos propres outils. Accès à l'API Magnetis  Cliquez sur API & connecteurs  Initiation à l'API  Vous pouvez ainsi : recueillir la liste de vos comptes clients et afficher leurs indicateurs ...
    • Comment supprimer un numéro tracké?

      Connectez-vous à votre compte Magnetis.  Si vous avez plusieurs comptes, allez dans la rubrique “Comptes en gestion”. Si vous n'avez qu'un seul compte, rendez-vous directement à l'étape 3 Sélectionnez le compte du numéro à supprimer en cliquant sur ...