Configuring WebHooks

This article was written to introduce WebHooks. Webhooks can send information from the CRM to another system via HTTP Post or JSON formats. 

You can set up WebHooks to post information from the CRM to other systems. You may do this to integrate outside systems. You can set up an HTTP Post using the GET or POST methods.

This article includes the following topics:

• Posting WebHooks
• Creating WebHooks
• Adding Key-Value Pairs
• Activating WebHooks

Posting WebHooks

To create a Webhook, you first need to get posting instructions from the system to which you will send information. They will most likely provide 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. 

1. From the Contacts tab, click Webhooks.
   
2. Name the Webhook and save it with the appropriate information.
   
   URL with Keys: The example information below shows the posting instructions provided with a URL and the keys that will be passed.
   
   Post URL: https://client.forthcrm.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 keys that should be passed. Notice the information is listed in one long string and starting at 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 pass the Key "firstname" with the value "test". This is referred to as a Key-Value Pair. Every Key has corresponding data you are passing as its value.

https://client.setforth.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 data for the WebHook.

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

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

Back to top

Creating WebHooks

Now that we have our posting information, we can set up the WebHook.

1. From the Contacts tab, click Webhooks.
   
2. Do the following in the appropriate fields (see the "Create A WebHook" image below):
   • Enter a name for the WebHook in the WebHook Title field.
   • Select an option from the *Execution Mode dropdown menu.
     • Background Job - Allows a WebHook to run in the background. Does not affect the usability of the system. Can 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.
   • Type a WebHook URL.
   • Type a Port number.
   • Select an option from the Method menu (POST or GET).
     

     NOTE
     If unsure of the method, select POST. During testing you can switch to GET if the post fails to function correctly with POST. If Posting instructions indicate a need to set the Port and/or Authentication Username and Password you can enter them at this point. 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.
     

   • 
3. Authentication refers to Access Authentication which is separate from the actual Webhook's URL. In the Authentication section, do the following:
   
   • Create a username.
   • Create a password.
   • Select an option from the Auth Type menu (Basic, Digest, or HMAC).
     
     

     NOTE
     Types of authentication are required. To learn more, click Basic, Digest or HMAC

4. Under the Headers section, select who this WebHook should be shared with from the Shared With dropdown menu (see image above).
5. Once you enter all requested information, click Save WebHook to proceed to add Key-Value Pairs.

Back to top

Adding Key-Value Pairs

1. Enter the Key in the Field Name input field
We will now add the Keys and then map data points from the CRM for the value we will pass. Start by entering the key as provided in the posting instruction or sample string.

IMPORTANT
Enter the key 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 with no changes to case, spacing or spelling.

2. Map the Field from within the CRM to the Key
The next step is to map 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 mapped the system field "First Name" to the Key "firstname" (see image above). 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 "Add" button to add it as a Key-Value Pair.

Constant Value - 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 (see image below).

IMPORTANT
If your form data is raw JSON, click on the "RAW JSON" link to enter that information.

3. Double Check and Confirm Before Saving

You will now see a new Existing Fields section, which now shows the firstname Key-Value Pair that you just added. Repeat the steps above to add additional Key-Value Pairs.

At this stage, before clicking the Save Webhook button, it is best practice to double-check that everything has been input correctly. Again, if any Keys are spelled incorrectly or differ 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 its system. This means they will not know what to do with the incorrect Key and will often omit it.

Special Parameters

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

Budget Fields

Budget Analysis fields can be passed between Forth CRM accounts via WebHook. This is done by using the Budget Tags. To begin, find the Tag corresponding to the Budget Field you are posting and posting into. Navigate to the Admin tab > Settings > Budget Fields page to locate 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.

To edit any particular field (in our example, we selected "Dividends"), click the pencil icon to the right of the field, and you will see an image similar to the one shown below to make your edits.

Back to top

Activating WebHooks

1. Execute WebHook
Location: Contacts tab > Client Dashboard

Inside the Client Dashboard, while viewing any contact, click the Execute WebHook button (see bottom left of the image below) to immediately activate a WebHook on that contact.

After clicking the red Execute WebHook button, a select dropdown menu appears. After choosing the desired WebHook, click the green Execute button (see below).

2. WebHook Triggers
Location: Contacts > Webhooks (on the left side at the bottom of the page); "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 whose payments 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 if the payment has been Returned / NSF. 

3. Mass Post
Location: Contacts Tab

Like Mass Editing, you may post a group of leads from the Contacts tab. The option is in the same dropdown menu as the Mass Edit and Export functions. While viewing the Contacts tab, 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 below we selected "With List" so all 58 contacts will be posted, If we select "With Selected" we would only be posting the three (3) contacts whose boxes were checked. After selecting, click the green circle icon with a checkmark next to the dropdown menu.

You will now be taken to the Mass Post page.

First, select the WebHook you want to activate from the Post Template dropdown menu. Once you've selected the WebHook, a preview of the data you post is displayed. Click "Next Record" to scroll through other records you will post 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 Sources

As part of importing leads via Data Sources, you can also have information posted via WebHook at the same time. You will find the option to select a WebHook at the bottom of the Data Sources editing page.

NOTE: Select from the Name/Field Assignment field before this option becomes available.

Highlight the WebHook you want to use and then save the Data Source. 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.

Back to top

Article Version History: