How to use, set up and test a webhook?

How to use, set up and test a webhook?

Why Use Magnétis Webhooks?

Webhooks allow you to automatically trigger an action (for example, towards your CRM) whenever a call is received on your tracked numbers, helping you connect your tools with call tracking. Unlike the API, which lets you actively fetch data and interact with the Magnétis interface, webhooks are managed by our system and notify you every time an event occurs on your tracked numbers.

If you’d like to perform one or several actions following the reception of a call on your tracked numbers, you can also explore the many possibilities offered by our Zapier integration.

Webhook Configuration

You can create webhook flows for your entire company, agency, or network of business locations in the Organization section of the Magnétis interface, whether for networks or specific accounts.

To do so, once logged in to the desired account or network, go to:
API & Connectors > Webhooks


To add a new webhook, click “Add an endpoint”, then fill in the following form:


  1. Title: a clear title to identify the webhook
  2. Endpoint: the URL address where the event sent by the webhook will be collected. This endpoint must contain the code that allows the data to be retrieved and integrated into your own tools
  3. Events: the type of event that triggers the sending of data to your endpoint URL. Available events include:
    • Call > At the end of a call [call:completed]
    • Call > When a call is missed [call:missed]
    • Call > When a call is ringing [call:ringing]
    • Email > When an email is received [email:received]
    • Lead > When a lead is created [lead:created]
  4. Customize this event (optional): you can select a group of accounts or numbers on which to execute this webhook, and define call duration conditions (in seconds) for its triggering.

Data Format Sent

As an example, here is a sample data format sent by a webhook of 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
The detailed data model is available in the following documentation: https://docs.magnetis.io/#calls-GETcalls--id-

Testing the Webhook

In the details of a webhook, the panel on the right allows you to test the webhook and send sample data to your endpoint. You will then get the response from your endpoint, both in status and data.
You can test the data models for:
  • CALL resource: corresponds to an incoming call
  • EMAIL resource: for tracked emails received
  • LEAD resource: when a lead is created after an incoming call or a tracked email
The last 10 attempts are displayed in the history section.


Request Signature and Securing Exchanges

Magnétis signs webhook requests so you can (optionally) verify that these requests are indeed generated by Magnétis and not by a third party pretending to be Magnétis.
If your application contains sensitive data, this ensures that the requests truly originate from Magnétis. This step is not mandatory, but it provides an additional verification layer.

Verifying the Webhook Signature

Magnétis includes an extra HTTP header with the POST data sent by the webhook:
X-CALLTRACKING-SIGNATURE
This header contains the request signature.
To verify a webhook request:
  1. Generate a signature using the same key as Magnétis.
  2. Compare it to the value in the X-CALLTRACKING-SIGNATURE header.

Getting Your Webhook Signature Key

When you create a webhook, a key is automatically generated.
You can view and reset this key from the Webhooks page in the details of the webhook.

Generating a Signature

In your code that receives webhook requests (the file defined as the destination URL / Endpoint):
  1. Create a string with the webhook URL, exactly as entered in the interface.
  2. Sort the POST variables of the request by key, in alphabetical order.
  3. Append each key and each value of the POST variables to the URL string.
  4. Hash the resulting string with HMAC-SHA1, using your webhook signature key to generate a binary signature.
  5. Encode the binary signature in Base64.
  6. Compare the generated signature to the one provided in the HTTP header X-CALLTRACKING-SIGNATURE.

Idea
Our support team is available to assist you with webhook integration. We can provide examples for data collection and signature verification.



    • Related Articles

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

    • Analyse des Appels par IA : Transformez vos conversations en insights marketing

      L'analyse des appels par Intelligence Artificielle (IA) est une fonctionnalité puissante de Magnétis qui va bien au-delà du simple call-tracking. Elle vous permet de plonger au cœur des conversations avec vos clients et prospects pour en extraire des ...

    • GDPR compliance

      Achieving compliance with the General Data Protection Regulation (GDPR) is a cornerstone of our commitment to data security and confidentiality at Magnétis. This documentary base has been crafted to offer a transparent and detailed overview of the ...

    • Quand y-a-t-il du hors forfait et comment est-il calculé?

      Le call-tracking Magnétis repose sur un système de forfaits mensuels qui incluent la majorité des usages standards. Toutefois, certains cas particuliers génèrent du hors forfait. Comprendre ces coûts additionnels est essentiel pour maîtriser votre ...

    • Connecter mes données de call-tracking Magnétis avec SalesForce

      Connectez votre CRM SalesForce avec le call-tracking Magnétis vous permettra d'intégrer automatiquement à vos pistes, tâches, contacts et campagnes les données d'origine de l'appel et le détail du modèle d'attribution. Deux solutions sont disponibles ...