How to use, set up and test a webhook?
Why using Magnétis webhooks ?
The webhooks allow you to launch an automated action (to your CRM for example) in order that each time you receive a call on your tracked numbers you will be able to connect these call-tracking data to your tools. On the contrary to the API that allows you to catch the information and to interact with the Magnetis interface, the webhook is generated by us and you are being notified each time an event is produced by your tracked numbers.
If you wish to realise one or several actions following the reception of a call on your tracked numbers, you can also explore the various possibilities offered by our Zapier integration.
Setting up the webhook
The webhook set up is done directly via the Magnétis platform in the section named "API & Conectors > Webhook".
In this section, you will be able to define the following parameters :
- The title of the webhook
- The endpoint, which corresponds to the point of destination that hosts the script which get and treat the sent data (https recommanded)
- The event type to send via the webhook. 4 types of events are available in the webhook :
- All calls
- Missed calls
- Conversions from the call-tracking visitor module (available if the visitor version module is active)
- Received text messages (only for Premium mobile tracked numbers)
- The webhook statuts
On the right side, you can use the functionalities to check the answer of the endpoint you've defined, send a test event and reenvoyer un évènement de test et reset the signature (in case you use the request signatures function).
Format of sent data
The webhook sends events in POST in a table to the endpoint mentioned in the platform.
The structure of sent variables is :
- ["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"]]
Variables in details :
- calltracking_event : contains the table with the variables of the call event
- idcall : unique Magnétis call identification
- accountname : name of the account in which is located the tracked number called
- date : reception date of the call
- trackednumber : Magnétis tracked number composed by the caller
- channelname : name the channel/support of call-tracking on which the number is broadcasted
- callingNumber : number of the caller (might be Anonymous if the caller is hidden)
- duration : duration of the call in seconds
- cid : Google Analytics ID (only on visitor version module)
- gclid : Google Ads ID (only on visitor version module)
- visitorevents : pages viewed, first page, last page, duration of visit
Queries signatures and securisation of exchanges
Magnétis signs the webhook queries so that you can (on option) check that these queries are generated by Magnétis and not by a tier that pretends to be Magnétis. If your application contains sensitive data, you will surely want to check that they are originating from Magnetis. This is not compulsory, but it offers a way for additional control.
Control of the query signature
Magnétis includes an additional HTTP header with the POST data sent by the webhook, the signature "X-CALLTRACKING-SIGNATURE", that will contain the query signature. To check a webhook query, you need to generate a signature that will use the same key as Magnétis's and compare it to the value of the header of the signature X_CALLTRACKING_SIGNATURE.
Obtain your Webhook signature key
When you create a webhook, a key is automatically generated. You are able to see and reset the key from the Webhooks page in your account, in detailled parameters.
Generate a signature
In your code the receives your webhook queries (file defined as an destination URL / Endpoint):
- Create a chain with the webhook URL, exactly the same way than you filled in in the platform.
- Select the POST variables of the query by key and by alphabetic order.
- Add each key and each value in POST variables to the URL chain
- Ajust the obtained chain with HMAC-SHA1, by using your webhook signature key in order to generate a binary signature.
- Code the binary signature in Base64
- Compare the binary signature that you generated to the signature in the http header of the signature X-CALLTRACKING-SIGNATURE.
Example in 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']);
- }
- }
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 à ...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 ...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 ...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 ...Conformité RGPD - Base documentaire
La mise en conformité avec le Règlement Général sur la Protection des Données (RGPD) est un pilier essentiel de notre engagement envers la sécurité et la confidentialité des données au sein de Magnétis. Cette base documentaire a été conçue pour ...