Configuring a Webhook

Webhooks allow your application to receive real-time data from one or multiple events occuring 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 in Dialog Insight.

Prerequisite

No specific requirements. This feature comes with the module. Before performing configuration of a a webhook, it is important to know the following information: Using and configuring webhooks are designed for advanced users how are familiar with custom coding. You, or any knowledgeable person, must configure a valid callback URL address where event notifications can be sent. To see how notifications for different events are presented, it is recommended that you create a test URL in Request Bin.

Access Path

> Configuration > External connections > Webhooks

 How To

1. Click on Create a webhook.
2. Enter the callback URL.
3. Check the events for which you want to receive data.
4. For each event, you can see an example of the sent JSON code, test data reception directly on your URL and, for message-related events, specify the mailing and communication types. By default, all types of communications and unitary mailings are checked.
   
   Description of message filters                 

   Filter	Description
   All types	All types of communications will be tracked.
   Specific types	Only the specified types of communications will be tracked.
   Unitary sending (confirmation, web service, test)	Only unitary mailings will be tracked.
   Batch or campaign	Either batch mailings or campaigns will be tracked.

5. If needed, validate that the webhook really comes from Dialog Insight by using the signature.
   See how to do this lower on this page.
6. If you want to be notified by email whenever a webhook is deactivated, select the desired recipients of the email in the list of users. Sending an email alert allows you to be certain you don't miss any event notifications.
7. Click Save.
8. When your parameters are set, click Activate.

For more details, view the Webhook User Guide.

Receiving a webhook

As soon as the webhook is configured, Dialog Insight can send a HTTP POST request on 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.

Replying to a webhook

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.

Validating the webhook

If you wish to, you can check if the webhook really comes from Dialog Insight using the signature sent in the header of the message. This HTTP header is named "X-DI-Signature".

How it works:

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.

Following are examples of C# and PHP signature validation.