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:
Title: a clear title to identify the webhook
-
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
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]
-
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.
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"
}
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:
-
Generate a signature using the same key as Magnétis.
-
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):
-
Create a string with the webhook URL, exactly as entered in the interface.
-
Sort the POST variables of the request by key, in alphabetical order.
-
Append each key and each value of the POST variables to the URL string.
-
Hash the resulting string with HMAC-SHA1, using your webhook signature key to generate a binary signature.
-
Encode the binary signature in Base64.
-
Compare the generated signature to the one provided in the HTTP header X-CALLTRACKING-SIGNATURE
.