Configuring JSON WebHooks

This article was developed to describe the use of Webhooks and JSON within Forth CRM. It is organized into the following sections:

Overview

Configuration Steps

Overview

JSON stands for JavaScript Object Notation. This open-stranded file format uses human-readable text to transmit data objects consisting of key-value pairs and array data types. It is easy for machines to parse and generate, and for humans to read and write.

JSON is built on two structures:

• Object - A collection of key/value pairs
• Array - An ordered list of values

JSON is a text format that is completely independent but uses conventions that are familiar to programmers of the C family of languages. (ex. C++, JavaScript, Python, etc.)

To learn more about JSON, click -->: https://www.w3schools.com/whatis/whatis_json.asp

 

Configuration Steps

1. Go to the Contacts Tab and select Webhooks from the Navigation Bar.
   
   The Webhooks Page will then open as seen in the image below.
   

2. Enter the JSON Endpoint/URL

Go to the WebHook URL* field and enter the JSON Endpoint/URL. This is the same step you would do for a traditional Key Value Pair post.

This URL/Endpoint will be provided by the receiving end in the posting instructions or sample string provided.

3. Add Headers and their Value in the Headers section

These should be given to you in the posting instructions from the receiving party.  Each post expects different items to be passed in the header. You can have as many headers as needed/required by the receiving party.

An example of a JSON header would be:  Header = "contentType"  and the Value = "application/json".

The Content-Type entity header indicates the media type of the resource. In responses, it indicates the content type of the returned content.

4. Click Save Webhook to save your information and to proceed to the JSON Request Type section.
5. Select "RAW JSON" to add a JSON Body to the WebHook.

6. Complete the JSON Body field

The JSON Body field is where you build out the JSON body for the webhook post.

JSON data is written as a key/value pair. A key/value pair contains a key name (in double quotes), followed by a colon, and then followed by the value (in double quotes). The key name will be given to you by the receiving party and the value will be the system field/custom field set up in the CRM.

Example: “first_name” : “{FIRSTNAME}”,

When adding more than one value, separate each row by a comma. Then, wrap your JSON values in brackets to open and close the container.

Example:

{
“first_name” : “{FIRSTNAME}”,
“last_name” : “{LASTNAME}”
}

7. Use of Multiple Fields

To add multiple fields to be passed to ONE field on the receivers' end, you can add containers within the main JSON container. For example, if you want the fields of {ADDRESS}, {ADDRESS2} {CITY} {STATE} and {ZIP} to all be passed to ONE address field on the receiver's end, set up the JSON container like the one below. This will tell the post to add those fields together to one field instead of 5 individual fields.

Example:

{
    "first_name": "{FIRSTNAME}",
    "last_name": "{LASTNAME}",
    "address": {
        "street": "{ADDRESS}",
        "street2": "{ADDRESS2}",
        "city": "{CITY}",
        "state": "{STATE}",
        "zip": "{ZIP}"
    }
}

Add the required fields stated in the posting instructions to the JSON Body in the format above. 

8. If needed, click Format JSON at the bottom of the JSON Body field to rearrange the JSON body into the correct format. 

9. Click "SAVE WEBHOOK " when finished.

10. Double-check posting instructions

Double-check the posting instructions to ensure you correctly set up the headers and JSON body.  You can then test the webHook on a test contact. If everything is set up correctly, you should get a “Success” result under the WebHook Results on the right-hand side of the WebHook page.

Article Version History: