Configuring WebHooks

This article describes how to configure, map, and execute WebHooks within the FORTH system. It was developed for CRM administrators and authorized users who need to configure automated integrations and transmit system data to third-party applications using WebHooks.

For information on configuring JSON WebHooks, see our Help Center article Configuring JSON WebHooks.

The article is organized into the following sections:

• Overview
• Prerequisites
• How to Access
• How it Works
• Troubleshooting / FAQ
• Assistance

Overview

WebHooks automatically send contact and system data from the FORTH CRM to outside tools like dialers, databases, or payment gateways, using HTTP requests. You can execute WebHooks automatically through event triggers, run them manually on single records, or process them in bulk across multiple contacts.

Prerequisites

• Standard user access to the FORTH CRM with permission to manage settings under the Contacts tab.
• Obtain the target URL and parameter requirements from the destination system before you can set up a WebHook. This is done by following these four steps:
  1. Identify the POST URL (Example: [https://client.setforth.com/post/example_hash/](https://client.setforth.com/post/example_hash/)).
  2. Identify all required Keys (Example: firstname, lastname, phone, state).
  3. If the destination system provides a single sample posting string, separate the base URL from the Key-Value parameters before proceeding.
  4. Any other authentication details, such as the required Username and Password, as well as the Auth Type ((Basic, Digest, or HMAC).

How to Access

1. Log in to the FORTH CRM.
2. Click the Contacts tab.
3. Select Webhooks from the navigation bar.
   

How it Works

Step 1: Create the WebHook

1. On the Webhooks page, provide a descriptive name in the WebHook Title field.
   
2. Select an option from the *Execution Mode dropdown menu.
   • Background Job - Allows a WebHook to run in the background. Does not affect 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 forces the system to run the WebHook immediately but prevents the User from navigating away from the page until the post is completed.
3. Enter the destination address in the WebHook URL field.
4. Enter a Port number if required by the target platform.
5. Select POST or GET from the Method menu. Select POST if the provider did not specify a method.

6. Configure access authorization in the Authentication section if required:

• Enter the required Username and Password.
• Select an option from the Auth Type menu (Basic, Digest, or HMAC). NOTE: When HMAC is selected as the auth type for a webhook, the following headers are automatically added to the webhook request: 
  • x-forth-signature
  • x-forth-signature-256

• 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 to proceed to add Key-Value Pairs.

7. Under Headers, select user access rights from the Shared With dropdown menu.
8. Click Save WebHook.

Step 3: Add Key-Value Pairs

1. Map the Data Point field from within the CRM to the Key
The value saved on the contact for that field will be passed as the value of the key.

In the example above, the system field "First Name" was mapped 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".

Constant Value - To pass a constant value for a Key, like an API hash or password, select the Custom Value option in the Value dropdown, and a third input field will appear for you to enter a constant value that will be passed for the Key (see image below).

Once you've selected the data point to use, click Add to add it as a Key-Value Pair.

3. Double Check and Confirm Before Saving

In the Existing Fields section, the system shows the firstname Key-Value Pair that you just added. Repeat the steps above to add additional Key-Value Pairs.

Double-check the entries under Existing Fields, then click Save Webhook.

Step 4: Activate the WebHook

Select one of four activation methods based on your workflow:

• Manual Execution (Single Contact): Navigate to Contacts > Client Dashboard. Click Execute WebHook in the lower-left section, select the WebHook from the dropdown menu, and click Execute.
  
• Automated System Triggers: Navigate to Contacts > Webhooks > WebHook Triggers. Map system events (such as status changes or payment failures) to run the WebHook automatically.
  
  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. 
  
• Mass Post (Bulk Contacts): 
  Navigate to Contacts. Select target records using With List or With Selected, then click the green checkmark icon. 
  
  Select the WebHook from the Post Template menu, review the data preview, and click Post Data.
  
• Data Source Imports: Navigate to Contacts > Data Sources. Select the WebHook from the bottom menu of the Data Source page, and click Save. Incoming leads trigger the WebHook automatically upon import.
  
  For more information on Data Sources, please visit our article titled Setting Up Data Sources: Web Forms and CSV Imports.

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, using 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 the example, we selected "Dividends"), click the pencil icon to the right of the field, and a Budget Setup page will appear to make your edits.

Troubleshooting / FAQ

Why is the receiving system missing data points sent by the WebHook?

Key names are case-sensitive and must match the destination system's parameters exactly. Check the Existing Fields list for spelling, spacing, or capitalization errors.

Which HTTP Method should I choose if my documentation does not specify one?

Select POST. If testing shows the post failed, edit the WebHook and switch the method to GET.

How do I pass budget analysis fields between two FORTH CRM accounts?

Navigate to Admin > Settings > Budget Fields to find the system tags. Enter the destination account's tag into the Field Name input, and enter the source account's tag into the Value field.

What headers does the system add when using HMAC authentication?

When you select HMAC, the system automatically adds the x-forth-signature and x-forth-signature-256 headers to the request.

Assistance

For further assistance, reach out to support@setforth.com.

Back to top