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) 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 :


  1. Titre : un titre explicite afin d'identifier le webhook
  2. 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
  3. Evènements : Evènement générateur de l'envoi des données vers votre endpoint URL. Les évènements disponibles sont :
    1. Call > À la fin d'un appel [call:completed]
    2. Call > Lorsqu'un appel est manqué [call:missed]
    3. Call > Lorsqu'un appel sonne [call:ringing]
    4. Email > Lorsqu'un email est reçu [email:received]
    5. Lead > Lorsqu'un lead est créé [lead:created]
  4. 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 :
  1. 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"

}

Info
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 :
  1. la ressource CALL : correspond à un appel entrant
  2. la ressource EMAIL : pour les emails trackés reçus
  3. 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) :
  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’en-tête http de la signature X-CALLTRACKING-SIGNATURE.
Idea
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 utiliser l’API de call-tracking ?

      L'API Magnetis vous permet d'intégrer le call-tracking dans vos propres outils. Structure et documentation La documentation comprenant la structure et l'utilisation de l'API Magnétis est disponible à l'adresse : https://docs.magnetis.io/ Vous y ...

    • 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 ...