Getting Started Guide for Inbound Webhooks (limited to some partners)

***Inbound Webhooks work with Webhook handlers (a type of connector). Connectors are limited to some of our technology partners. If you would like to connect your system to your Dialog Insight project, our team can provide a solution that fits your needs and data structure.***

To send webhooks from a third-party system to a Dialog Insight project, you must create a Webhook Handler. The Webhook Handler generates a URL (endpoint) to call to send your data. Specifically, when an event occurs in the third-party system, it triggers a call to this Dialog Insight URL.

Note: If you want to create a connection in the other direction (from Dialog Insight to a third-party system, please refer to the guide on outbound webhooks).

In this article, you will see how to set up the necessary structure for the connection using an example in which we will connect data from a contact list AND a transaction list.

Requirements

• Create the destination for contacts
• Create a destination for transactions

For the example presented in this article, we will use the email as the primary key. However, you could use another type of key to manage contacts.

Step 1: Create the Webhook Handlers

To create a connection for Contacts and for Transactions, you must create 2 webhook handlers (one for Contacts AND one for Transactions).

To create a handler, follow the access path and click Create :To use this interface (SU External webhook Handler), you must have the necessary permissions.

Extension de path
In the creation window, add a Path extension:

The recommended format is [integration]/[object]/[action]

Integration: the third-party system that sends the data
Object: the table that sends the data
Action: the method of data processing

Authentication mode
Indicate which authentication mode to use, depending on which is compatible with the third-party system.

Step 2: Add the Transformation Scripts

A transformation script is a DI# script that directs what to do with the data when a payload is received in Dialog Insight. The payload comes from an incoming webhook. Transformation scripts will convert the data received in the endpoint (the webhook handler URL) before sending it to the contact list or transaction table.

Most of the time, our team will provide you with a transformation script during the initial support. Simply add the scripts in their respective webhook handler (Contacts or Transactions). However, you could create the script by yourself or modify an existing one. If it is the case, see the procedure below.

Transformation scripts examples
These scripts are examples to adapt to your case.

// Transformation script example for Contact
datasource contacts = context.Payload;
datasource contactListUpdater = System.Operations.ContactListUpdaters.GetCurrent();
datasource mapping = System.Operations.Mappings.Get(contactListUpdater, "ContactMapping");

foreach (contact in contacts)
{
    datasource contactDataSource = system.SourceHelper.CreateCollection();
    
    // Contact Fields
    contactDataSource.SetValue("email", contact.email);
    contactDataSource.SetValue("firstName", contact.firstName);
    contactDataSource.SetValue("lastName", contact.lastName);
    contactDataSource.SetValue("address", contact.address);
    contactDataSource.SetValue("app", contact.appartment_number);
    contactDataSource.SetValue("city", contact.city);
    contactDataSource.SetValue("province", contact.province);
    contactDataSource.SetValue("country", contact.country);
    contactDataSource.SetValue("postalcode", contact.postal_code);
    contactDataSource.SetValue("phone", contact.home_phone);
    contactDataSource.SetValue("mobile", contact.mobile_phone);
    
    // Mapping processing and data loading
    datasource mappedContact = mapping.MapWithMappingBase(contactDataSource);
    contactListUpdater.Merge(mappedContact);
}

// Transformation script example for Transaction (the standard table in Dialog Insight)
datasource transactionPayload = context.Payload;

datasource transactionUpdater = System.Operations.RelationalTableUpdaters.GetByCode("ECommerce_Transaction");
datasource mapping = System.Operations.Mappings.Get(transactionUpdater, "TransactionMapping");

foreach (trx in transactionPayload)
{
    datasource trxDataSource = system.SourceHelper.CreateCollection();
    
    trxDataSource.SetValue("id", trx.id);
    trxDataSource.SetValue("email", trx.email);
    trxDataSource.SetValue("status", trx.status);
    trxDataSource.SetValue("price", trx.price);
    
    // Mapping processing and data loadi
    datasource mappedtrx = mapping.MapWithMappingBase(trxDataSource);
    transactionUpdater.Merge(mappedtrx);
}

Step 3: Create the Mappings

Go to Project → Data Management, and, under Integrations, click Advanced Configurations. 

In the Mappings section, you must add a mapping for contacts AND another for transactions:

Example of mapping for ContactLegend 

Step 4: Call the Callback URL

When a webhook handler is created (you must save and go back into the handler), a callback URL is generated:

C = Account number in Dialog Insight
P = Project number in Dialog Insight
W = Webhook number

You must indicate to your third-party system the URL to call for synchronizing your Contacts AND the URL for Transactions.