Configuring a Webhook

Webhooks allow your application to receive real-time data from one or multiple events occurring in the Dialog Insight platform. For example, you might want to create a webhook to get the information about a new contact in order to add it to your system or app.

To use a webhook, you must provide a destination URL where you send the notifications and select where and when you want to receive data related to your contacts or messages. Dialog Insight sends this data to your system when the selected events are triggered. You must then confirm to Dialog Insight that you received the notification. 

The goal of a webhook is to transfer the data from DI to your system. To transfer data in the other direction, from your system, you must use the Web services. 

Warning! This feature is for users with advanced knowledge in programming!

The date of birth of a contact is modified in Dialog Insight. Dialog Insight sends a notification to the callback URL. Your system must confirm the reception of this notification as soon as possible to avoid repeated tries for the same query. Your system processes the received data according to the implemented automated procedures (e.g. CRM update).

For more details on the events that are supported, see the Guide on the Webhook Triggers.

Requirements

• Provide a callback URL for the destination in your system or app. You, or any competent person, must configure that URL in your system so it can receive the notifications.
• Understand the programming principles related to the use of webhooks (this feature is for advanced users).

Step 1: Add the Callback URL

Follow the access path and click Create a Webhook. Then, indicate the callback URL (the destination for the webhook in your system):

Step 2: Select the Events

Check the event (updates) which will trigger the data transfer to your system:

To learn more on the data that are sent for each event, you can use the Example button or the Test button at the right of an event:Example will provide you with an example of the sent values in JSON (this can be different with the data that are really sent depending on your project struture).

Test allows you to send a test directly to the callback URL. The sent data will contain the field isTest with the True value (isTest: true).   

To push your tests further, you could create a webhook that sends data to a request bin. Be careful not to send sensitive data to a request bin.

Step 3: Add a Signature

To add a layer of protection that validates the webhook is really coming from Dialog Insight, you can add a cryptographic signature. This section appears when you click Save. 

This signature will be added to the header. This HTTP header is named "X-DI-Signature".

1. The webhook is sent to your URL.
2. Your page retrieves the HTTP header named "X-DI-Signature".
3. Your page checks the value of the "X-DI-Signature" against the public XML or PEM key (provided on the webhook's configuration page).
4. If the comparison is valid, then you process the received data, otherwise you reject the call.

At the end of the article, you will find examples to download of C# and PHP signature validation.

Step 4: Add an SSL Certificate 

To add a layer of protection, you can add an SSL certificate in the Client certificate authentication section. This section appears when you click Save. The certificate (which contains a private and public key) can be added manually or with .pfx file:

Step 5: Add Email Alerts

If you want, you can add alerts to notify users of your account by email. Alerts are sent in the following cases:

• After the 1^th, 10^th, 100^th, 1000^th, 10000^th error of each day (based on Dialog Insight' server time).
• When your webhook has been automatically deactivated.

Step 6: Configure the Webhook Reception

As soon as the webhook is configured, Dialog Insight can send an HTTP POST request to the URL you have specified each time the requested events occur. The POST request parameters contain data (in JSON format) related to the event. In fact, this data corresponds to all the fields in the project. To manage the received notifications, it is recommended to accept all notifications sent by Dialog Insight and to process them one by one.

Example in C# for accepting the notifications in a file .ashx
<%@ WebHandler Language="C#" Class="WebHookHandlerExample" %>
using System; 
using System.Web; 
using System.IO; 
using System.Text; 
public class WebHookHandlerExample : IHttpHandler  
{ 
public void ProcessRequest (HttpContext context)  
{ 
// Read the posted JSON body 
string json; 
using (StreamReader stream = new 
System.IO.StreamReader(context.Request.InputStream, Encoding.UTF8)) 
{ 
} 
json = stream.ReadToEnd(); 
// Do not process event contents here : queue the event to be 
processed asychronously. 
// Exemple: dumping to a file 
string filename = String.Format(@"C:\Temp\webhook-event-{0}.json", 
Guid.NewGuid().ToString()); 
File.WriteAllText(filename, json); 
} 
public bool IsReusable  
{ 
get { return false; } 
} 
} 

Example in PHP
// Read the posted JSON body 
 $json = file_get_contents('php://input'); 
 // Do not process event contents here : queue the event to be processed 
 asynchronously. 
 // Example: dumping to a file 
 $myfile = file_put_contents('C:\\temp\\webhook-event-' . uniqid('', true) . 
 '.json', $json); 
 ?>

Responses to the Webhook
Votre application doit confirmer la réception de la notification avec une réponse HTTP dont le code est 200 (statut = OK) . Toute réponse en dehors de cette gamme indiquera à Dialog Insight que vous n’avez pas reçu votre webhook.

Dialog Insight fera jusqu'à 5 tentatives d'envoi sur une période d'environ 2 heures.

Your application must confirm the reception of the notification using an HTTP reply where the 200 code status is OK . Any other reply will be considered as a no-reply and Dialog Insight will make 5 more tries over a 2-hour period.

Delivery Attempts
A notification is sent as soon as a targeted action is performed in Dialog Insight’s platform using a POST (http / https). This POST has a 15 second timeout. Then, we will make 4 more attempts in the next 2 hours to resend the notification if we have not received an HTTP response with an OK code (code = 200). These attempts are scheduled as follows:

• 1^st attempt: when the action is performed  
• 2^nd attempt: 1 minute later 
• 3^rd attempt: 15 minutes later (16 minutes after the action)   
• 4^th attempt: 30 minutes later (46 minutes after the action)
• 5^th attempt: 60 minutes (101 minutes after the action)  

If the notification still can’t be delivered after these attempts, it is placed in error and abandoned.

Automatic Deactivation
Notifications are automatically deactivated if you experience a system failure, to prevent a large number of messages blocked after multiple attempts. Your system will be considered in failure when at least 100 consecutive errors have occurred within a minimum of 8 hours. This webhook will then be deactivated and an alert will be sent to users set to receive alerts related to this webhook.

To reactivate notifications, you must activate it again through the platform. Note that notifications that should have been sent during the deactivation period will be lost (as well as notifications that were pending during this period).

Step 6: Activate the Webhook

When the webhook is ready to use, click Activate. 

Once a webhook is enabled, Dialog Insight will send all the requested notifications. Depending on the number of interactions done by contacts or based on the number of errors, there can be quite a lot of notifications. So, it is not recommended to process these notifications as they arrive, since any processing error or delay can cause notifications to be lost.

The purpose of the system that receives webhook calls is to accept the responsibility of the notification as soon as possible and to confirm its reception.

For this reason, we recommend you use an asynchronous system that automatically registers all the notifications sent by Dialog Insight in a database or file. Then, you can use another automated process to manage one notification at a time to produce the final result – add contacts to your CRM, update contacts based on your rules, etc.