Callback
  • 04 Apr 2023
  • 6 Minutes to read
  • PDF

Callback

  • PDF

Article summary

Purpose

The Cloudingo Integration Callback API allows Enterprise customers to be notified of events occurring in the Cloudingo platform. Enterprise systems can take appropriate actions based on these event notifications to keep multiple disconnected systems in sync and up-to-date. The power to find duplicates and merge data into records using Cloudingo can also improve data quality in your system as well. 

System Design

The Cloudingo platform runs in its own cloud, separate from Salesforce. The setup and configuration involves connecting Cloudingo to your Salesforce cloud. Cloudingo has several mechanisms for merging, converting, updating and deleting data. Whether manually performing these actions (single record or in mass), using automation jobs, or using the integration web service API, notifications can be received when the operations succeed or fail.

The callbacks are configured in Cloudingo. Simply specify the type of callback and which events should be received.

Proprietary Indexing

Cloudingo leverages its own indexes for finding duplicates. These proprietary indexes allow for more complex duplicate scenarios than can be supported in Salesforce Apex and SOQL. The Cloudingo system is also unrestricted by Salesforce governance (CPU limits, query result sizes, looping maximums) because indexes on the Cloudingo cloud servers are used to perform searches.

Newly created or modified records in Salesforce result in index updates in the Cloudingo platform. The speed at which these updates occur is dependent on the system load for both the Salesforce and Cloudingo servers, as well as the Cloudingo synchronization mode being used for your account. An understanding of index updates is fundamental to understanding results. Usually, the timing of index updates is not an issue, but when data is flowing into Salesforce from multiple sources simultaneously, duplicate detection will depend on the indexes being up-to-date.

Callback Technologies

The current version supports webhooks using both the HTTP GET and HTTP POST protocols. 



  1. The Cloudingo Integration dashboard can be accessed by logging into https://app.cloudingo.com. Once logged in, the user is presented with the Dedupe dashboard by default. To access the Cloudingo integration dashboard, choose the 'Integrations' → 'Manage' option from the left-hand-side navigation window. 

  2. At the top of the page, choose the 'Callback' tab.


  3. If no integrations have previously been created, the screen will automatically display an option to 'Create New'. The option is also available under the 'Actions' menu.

  4. After choosing the option to create a new Callback, you will be taken to the Callback service integration Create screen.


Step 1: Cloudingo settings

  1. Integration Name: Give the integration a descriptive name.
  2. Salesforce Account: Choose the desired Account that the integration will apply.
    1. If only one org is connected to Cloudingo, it will default automatically.
  3. Callback Type: Choose the desired callback type.
    1. HTTP Get 
    2. HTTP Post
  4. Enable Integration: Choose this option to enable the integration.
    1. Deselect to disable the integration.


Step 2: Web Hook settings



  1. Web Hook Base URL: Populate the base address for the webhooks. 
    1. For example, "https://yourcompany.com".
    2. All webhooks will be prefixed with the base address when called.
    3. If using multiple addresses, set up multiple integrations.
  2. Add Header:
    1. Name: Give the header a descriptive name.
    2. Value: Populate the header value based on what the endpoint needs if necessary.
      1. For example, 'Content-Type: text/JSON' if authentication is required on the endpoint and requires a value for recognizing the content or similar.
  3. Add Web Hook:
    1. Object: Choose the object that will be monitored (Lead, Contact, Account, etc.)
    2. Event: Choose when the event should occur (when the Merge Succeeded, Merge Failed, Convert Succeeded, Convert Failed, Pre-Merge, or Pre-Convert). 
      1. Supported events are listed below.
    3. Web hook URL suffix: Enter the endpoint for the webhooks.
      1. For example, "https://yourcompany.com/suffix".
    4. Tokens: Populate the token.
      1. Tokens will determine either the query parameters or post parameters.
      2. For example, "https://yourcompany.com/suffix?token".
      3. Tokens will provide details on the event that triggered the callback (Master IDs, Child IDs, Event, Reason, Action, Task ID, New ID, or Object).
  4. Test: Choose this option to test the webhook.


Supported Events

The following section details the available events in which callback notifications can be received from the Cloudingo Integration Callback API. In the current version, Cloudingo supports the following event notifications: Merge Succeeded, Merge Failed, Convert Succeeded, Convert Failed.

Select which of these events notifications should be received. By default, no notifications are sent. A URL template must be provided to call with macros to indicate where to place values from the current event. 

EventAvailable MacrosMacro DescriptionVersion
MergeSucceeded
${MasterID}The Salesforce external ID (18 character) of the record that was kept after the merge operation completed.1.0

${ChildIDs}The comma separated list of the Salesforce external IDs (18 character) of all the records that were eliminated during the merge operation.1.0

${NewID}The Salesforce external ID (18 character) of the record that is created, in the event that a new record was created during the merge operation.1.0

${Event}The event name, "MergeSucceeded" in this case. This macros is used if multiple events are tied to the same URL and an indication is needed to determine what happened.1.0
MergeFailed
${MasterID}The Salesforce external ID (18 character) of the record that was attempted to be retained as the master in the merge operation.1.0

${ChildIDs}The comma separated list of the Salesforce external IDs (18 character) of all the records that were meant to be eliminated during the merge operation.1.0

${NewID}The Salesforce external ID (18 character) of the record that is created, in the event that a new record was created during the merge operation.1.0

${Event}The event name, "MergeFailed" in this case. This macro is used if multiple events are tied to the same URL and an indication is needed to determine what happened.1.0

${Object}The Salesforce object type that the merge was attempted on (Lead, Contact, Account).1.0

${Error}The error message associated with the merge attempt.1.0
ConvertSucceeded
${MasterID}The Salesforce external ID (18 character) of the record that was kept after the convert operation completed.1.0

${ChildIDs}The comma separated list of the Salesforce external IDs (18 character) of all the records that were eliminated during the convert operation.1.0

${Event}The event name "ConvertSucceeded" in this case. This macro is used if multiple events are tied to the same URL and an indication is needed to determine what happened.1.0

${TargetObject}The Salesforce object type of the target record in the convert (Contact or Account).1.0

${SourceObject}The Salesforce object type of the source record(s) in the convert (Lead).1.0
ConvertFailed
${MasterID}The Salesforce external ID (18 character) of the record that was attempted to be retained as the master in the convert operation.1.0

${ChildIDs}The comma separated list of the Salesforce external IDs (18 character) of all the records that were meant to be eliminated during the convert operation.1.0

${Event}The event name, "ConvertFailed" in this case. This macro is used if multiple events are tied to the same URL and an indication is needed to determine what happened.1.0

${TargetObject}The Salesforce object type of the target record attempted in the convert (Contact or Account).1.0

${SourceObject}The Salesforce object type of the source record(s) attempted in the convert (Lead).1.0

${Error}The error message associated with the convert attempt.1.0




Sample Scenario

In the example below, we have setup a temporary demonstration Webhook to alert us of successful Lead and Account merges to give us the associated record IDs.



Webhook & Parameters
A - LEAD?Action=Merged&mid=${MasterID}&cids=${ChildIDS}&fnames=${ChildFields:First Name}&lnames=${ChildFields:LastName}
B - ACCOUNT?Action-Merged&mid=${MasterID}&cids=${ChildIDs}


When a Lead is merged successfully in Cloudingo, an event will fire making a GET request to the example URL as follows:

The macros will populate the Salesforce IDs along with the FirstName and LastName on the records (master and children).

On the Integration Dashboard, you can see the Callback defined with a base URL and two Webhooks.

You can see that so far, no Callbacks have been made and no errors registered. Merging a lead or account in Cloudingo will trigger the callback to be made.



Callback Activity Report

  1. To see the details of the Callbacks that have been made, navigate to the Reports Dashboard by choosing the 'Reports' → 'Reports' option from the left-hand-side navigation window.

  2. Search for the Callback Integration Activity report on the reports dashboard. 
    1. If the report is not enabled, you can enable it under 'Actions' → 'View Reports' (top right in the reports dashboard).
    2. Check the box next to the report name and 'Save'.

  3. The report output will provide the ServiceName, Method, Status, StatusMessage, & Date.

Was this article helpful?

What's Next