|February 20, 2024
This article was written to introduce WebHooks. Webhooks can be used to send information out of the CRM to another system via HTTP Post or JSON formats.
This article includes the following topics:
To create a Webhook, you first need to get posting instructions from the system you are going to be sending information. 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.
- From the Contacts tab, click Webhooks.
Name the Webhook and save it with the appropriate information.
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.forthcrm.com/post/f16b3893c9cf77f6348fa42444979913a6dad41a/
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 its value.
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 properly.
Now that we have our posting information, we can set up the WebHook.
From the Contacts tab, click Webhooks.
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.
- 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.
- Type a WebHook URL.
- Type a Port number.
- Select an option from the Method menu (POST or GET).
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.
Authentication refers to Access Authentication which is separate from the actual Webhook's URL. In the Authentication section, do the following:
- Under the Headers section, select who this WebHook should be shared with from the Shared With dropdown menu (see image above).
- Once you enter all requested 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.
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).
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 that they won't know what to do with the incorrect Key and will often omit it.
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.
|Enrollment Plan Data
|Copy all uploaded files in "Signed Contract / Gateway Authorization" to "Signed Contract / Gateway Authorization" of the specified Forth Account/ID.
|Upload Signed Documents
Budget Analysis fields can be passed between Forth CRM accounts via WebHook. This is done by using the Budget Tags. To begin, locate the respective Tag that corresponds 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 (for our example we will select "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.
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 selection dropdown menu will appear. After choosing the desired WebHook, press 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 in the event payment has been Returned / NSF.
3. Mass Post
Location: Contacts Tab
Similar to Mass Editing, you may post a group of leads from the Contacts tab. The option is located in the same drop-down 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. Once you have made your selections, click the green circle icon with a checkmark next to the drop-down 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 will be posting is displayed. Click "Next Record" to scroll through some 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 Sources
As part of importing leads via Data Sources, you can also have information posted out 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: You must make a selection from the Name/Field Assignment field first before this option becomes available.
Highlight the WebHook you wish 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.
Article Version History:
|Formatting Review only - no subject matter updates
|Updated for Forth rebranding; Added header and version control footer.
|Replaced three screenshots at the beginning of the article to reflect the current user interface and to improve legibility.
|Updated table in the "Special Parameters" section of the article.