WebHooks

You are able to setup WebHooks in order to post information out of the CRM to other systems. You may do this to integrate outside systems. You can setup a HTTP Post using a GET or POST methods.

Location: Contacts Tab > WebHooks

Posting Instructions and Sample Strings

To create a WebHook you will need to get posting instructions from the system you are going to be sending information to. They will most likely provide either a URL and a set of Keys to pass or an example posting string containing the URL and Keys. In the example below we are posting a simple set of data. The contacts first name, last name, phone number and state code.

Examples

URL with Keys: The example information below is where the posting instructions have been provided with a URL and the keys that will be passed.

Post URL: https://client.debtpaypro.com/post/f16b3893c9cf77f6348fa42444979913a6dad41a/

Keys

• firstname
• lastname
• phone
• state

Sample String: Below is an example where a sample string has been provided, which is simply the Posting URL including all the keys that should be passed. Notice the information is listed in one long string and starting at the '?' the keys are separated by a '&' symbol. After each parameter is a sample set of data. The first Key is included as "firstname=test". This means we are passing the Key "firstname" with the value "test". This is referred to as a Key-Value Pair. For every Key there is corresponding data you are passing as it's value.

https://client.debtpaypro.com/post/f16b3893c9cf77f6348fa42444979913a6dad41a/?firstname=test&lasname=test&phone=5555555555&state=CA

If given a sample string you will want to separate the Post URL from the Key Value Pairs like below. Having the URL and Keys organized this way will help you when entering the data for the WebHook properly.

https://client.debtpaypro.com/post/f16b3893c9cf77f6348fa42444979913a6dad41a/

firstname=test
lasname=test
phone=5555555555
state=CA 

Create a WebHook

Now that we have our posting information we can setup the WebHook. Start by entering a Title, WebHook URL, *Execution Mode, and select the method. If you are unsure of the method select POST to start with. During testing you can switch to GET if the post fails to function correctly with the POST method. If Posting instructions have indicated the need to set the Port and/or Authentication Username and Password you can enter them at this point as well. The Port and Authentication are not required for the WebHook to function. Also, do not mistake the Authentication Username and Password for Key Value Pairs that your posting instructions indicate need to be passed.

• *Execution Mode
  Background Job - Allows the Webhook to run in the background. Does not affect usability of the system. Can sometimes be delayed while the system runs through each Webhook in the queue.
  Inline - Immediately runs the Webhook upon execution by a User. This mode has the benefit of forcing the system to run the Webhook immediately but will prevent the User from navigating away from the page until the post is completed.

*The Authentication refers to Access Authentication which is separate from the actual WebHook's URL and you can use Basic or Digest Types if authentication is required. 


Once you have entered information, click "Save WebHook" and move to the next step of adding the Key Value Pairs.

Adding Key Value Pairs

1. Enter the Key in the Field Name input field

We will now be adding the Keys and then mapping data points from the CRM for the value we will be passing. Start by entering the key as provided in the posting instruction or sample string.

*Important: The key must be entered exactly as it exists in the system you are posting to. In our example the instruction provided uses "firstname" as the Key. If "Firstname", "First Name", "fname" or anything straying from the instructed "firstname" is used, the post will not work. The Key MUST be entered verbatim to what is provided, no changes to case, spacing or spelling.

2. Now Map the Field from within the CRM to the Key

The next step is to map together the data point from within your CRM to the Key. The value saved on the contact for that field will be passed as the value of the key. In our example below we have mapped the system field "First Name" to the Key "firstname". This means when the WebHook runs, the value for the system field "First Name" will be passed as the value for the Key "firstname". For example if the contact's first name is saved as "Mike" the Key "firstname" will be passed with the value "Mike". Once you've selected the data point you wish to use, click the green circle icon with the white plus symbol to add it as a Key Value Pair.

*Constant Value - In the case you need to pass a constant value for a Key like an API hash or password you can select the "Custom Value" option for the Value and a third input field will appear for you to enter a constant Value that will be passed for the Key.

3. Double Check and Confirm
Now that you have added all the Key Value Pairs for the WebHook, it is best practice to double check that everything has been input correctly. Again, if any Keys are spelled incorrectly or differing in any way from what was provided in the posting instructions or sample string, the value will not be passed. The system receiving the post will not be able to capture the data since it is looking for a Key that doesn't exist in their system. This means that they won't know what to do with the incorrect Key and in most cases will omit it.

Special Parameters

There are a few special parameters that can be passed when posting contact data between two Debt Pay Pro CRMs. The Field Name and Value should be copied exactly as they are displayed below. On the receiving Data Source, these parameters should be left un-mapped.

Budget Fields

Budget Analysis fields can be pass between DPP CRM accounts via WebHook. This is accomplished by utilizing the Budget Tags. You will need to locate the respective Tag that corresponds to the Budget Field that you are posting, and posting into. Navigate to the Admin tab > Settings > Budget Fields page to located these Tags.

When setting up your Webhook, the Budget Field Tag of the destination CRM will be used as the Field Name, and the Budget Field Tag of the posting CRM will be used as the Value.

How to Activate a WebHook

1. Execute WebHook
Location: Contacts tab > Client Dashboard

From inside the Client Dashboard while viewing any contact, you can click the Execute WebHook button to immediately activate a WebHook on that contact. After clicking the large red Execute WebHook button, a selection box will appear. After choosing the desired WebHook, simply press the green Execute button.

2. WebHook Triggers
Location: Linked on WebHook setup page on the left side; "Setup WebHook Triggers"

Similar to Email Triggers, system events can trigger the WebHook to run. For example if you use a phone dialer and have a call queue dedicated to calling clients who's payment have been returned, you could set up a WebHook that posts contact information to the call queue in the dialer. Then set up a trigger to use the WebHook in the event a payment has been Returned / NSF. 

3. Mass Post
Location: Contacts Tab

Similar to Mass Editing, you are able to Post a group of leads from the Contacts tab. The option will be located in the same drop-down menu as the Mass Edit and Export functions. While viewing the Contacts tab you will need to select either "With List" (post the entire list you are viewing) or "With Selected" (post only contacts you've selected by checking the box next to their record on the list table). In the example displayed below we have selected "With List" so all 76 contacts will be posted, If we selected "With Selected" we would only be posting the 3 contacts who's boxes we have checked. Once you have made your selections click the green circle icon with a check mark next to the drop-down menu.

Once you have clicked the icon, you will be taken to the Mass Post page. First select the WebHook you want to activate from the drop-menu displayed. Once you've selected the WebHook a preview of the data you will be posting is displayed. Click "Next Record" to scroll through some of the other records you will be posting to check the data. Once you have confirmed everything is ready, click "Post Data". Depending on the number of records you are posting, the time it takes for the WebHook to run will vary. Once finished you will be taken back to the Contacts Tab.

4. Automatically Post from Data Source
Location: Contacts Tab > Data Source

As part of importing leads via Data Sources, you can also have information posted out via WebHook at the same time. You'll find the option to select a WebHook at the bottom of the Data Source editing page. Simply highlight the WebHook you wish to use and then save the Data Source. Now the next time a lead is imported through the Data Source, it will also activate the WebHook.

For more information on Data Sources, please visit our articles for setting up an Import or WebForm Data Source.