Setting up Webhooks

Step 1 : Create a webhook

1. Log in to the Zoho Developer Console and navigate to Vertical Solutions.
   
2. Choose the application you wish to modify and select Edit.
   
3. Click on Automate > Workflow > Webhooks
   
4. Click on Configure Webhook.
   
5. Specify the following:
   
1. Name - Alphanumeric (100): An identifier for your webhook.
   
2. Description - 200 characters : Add a short description for your webhook
   
3. METHOD - Picklist : Select the HTTP method from POST, PUT, GET, DELETE.
   
1. POST allows you to enter the values in the fields of the associated application.
   
2. GET allows you to retrieve information to update in the fields of a record in Zoho CRM
   
3. PUT updates the existing value in the associated application.
   
4. DELETE deletes the existing value in the associated application.
   
4. URL to notify (300 characters) : The URL for the external application, where the notifications are to be sent.
   
5. Module (Picklist): Choose the module. The primary modules like  Leads, Accounts, Contacts, Deals, etc are supported, along with Tasks and Meetings.
   
6. Specify the necessary Header information. Parameters added to the header section will have data that will synchronize with the header of other application. In addition to the trigger information, header can customarily carry API Keys/ Auth tokens. To form the Header URL parameters, choose Module Parameters and/or Custom parameters. 
   LIMIT : A webhook can accommodate up to 10 Header URL Parameters.
1. Module Parameters: Specify the Parameter Name, Parameter type, and corresponding Parameter Value. Add multiple parameters to build the string. This format is dynamic, and you have options to choose the field values from the picklist. The Parameter Type includes the primary modules, Users and Organization.
   
2. Custom Parameters: Specify the Parameter Name and corresponding value for the webhook. Since the value in a custom parameter is static, this key/value pair is primarily utilized for sending authentication tokens, security tokens, API keys, and similar data.
   
7. Body : Select the Body type and specify the required details. The body part of the URL contains information about the trigger to another application. You can configure the body using either Form-Data or Raw, selected from the picklist.
   
1. Form-Data : This option allows you to construct the body of the URL by combining the Parameter Name, Parameter Type, or Parameter Value. Form-Data can be built in three ways: Module Parameters, Custom Parameters, and User-Defined Parameters.
   
1. Module Parameters : Add the Parameter name, type, and value from the dropdowns.
   
2. Custom Parameter : Add the parameter name and value.
   
3. User Defined Format : Define the Parameter name and its value. This format is dynamic, allowing you to select the type of value from the insert merge field option using #.
   
2. Raw Data : Besides forming parameters, you can also enter your own data values in the text editor when selecting Raw Data as the body type. You can input data in XML, JSON, HTML, or TEXT formats. Additionally, you can use the # merge field feature to reference a field value within the script. A webhook can hold up to 15000 characters in the raw data text editor.
   
8. The Preview URL feature displays the complete webhook URL for GET and DELETE request methods. However, for the POST and PUT methods, only the configured URL is displayed. To preview the URL, click the Refresh icon located at the bottom of the text editor. You can also copy the URL for reference.
   
9. Click on Save
   

1. When the Request Method is set to POST or PUT, the configuration options for Header and Body are displayed.
   
2. If the Request Method is set to DELETE, the options for Header and Form-Data in the body configuration are displayed.
   
3. For a Request Method set to GET, only the body configuration in form-data format is visible.
   
4. In the Meetings module, it is not possible to utilize personal details of participants like Email, Phone, Mobile, etc., as parameters in a webhook.
   

Important Notes:

1. Data retrieval from external apps to the solution is not possible.
   
2. Regularly update the API ticket according to the limits set by third-party applications. to avoid disruptions.
   
3. You will not receive email notifications if the webhook integration stops functioning due to an issue in a third-party API.
   
4. If a webhook fails, it will send an initial notification. A second notification will be sent after 15 minutes. After this, no further notifications will be sent for that particular workflow trigger.
   
5. If you exceed the maximum webhook limit for the day, the system will stop sending remaining webhook notifications to third-party applications and notify the Administrator of the failure.
   
6. In the URL to Notify field, you can specify port numbers. Please note that only ports 80 and 443 are supported.
   
7. Vertical Solutions provides an option to select the required Date/Date Time format and Time Zone during webhook parameter configuration.
   
8. Limits for Webhooks is 500,000 calls/day or 500 calls/user/day (whichever is lower).
   

Troubleshooting Unsupported Merge Fields in Webhooks

1. Deleted Custom Fields: If a custom field or custom lookup field used within a webhook's Value Description editor is subsequently deleted, the corresponding merge field value will become unsupported. To rectify this, update the Value Description editor to utilize currently available fields.
   
2. Module Incompatibility: Merge field values are specific to their corresponding modules. Using a merge field designated for the Leads module within the Value Description of a Deals module will result in an unsupported field error. Ensure you employ merge fields relevant to the chosen module.
   
3. Disabled Features: Certain features, such as Google Ads Integration or Visitor Tracking, create custom fields. Disabling these features renders the associated merge fields unsupported. Be mindful of potential limitations when working with disabled features.
   

Best Practices for Accurate Merge Fields:

1. Conduct periodic reviews of your webhooks to identify and update any outdated merge field references.
   
2. Verify that the chosen merge fields align with the specific module you are working within.
   
3. Maintain awareness of disabled features and their impact on available merge fields.
   

Webhook Error Codes

Webhook execution may sometimes fail due to one of the following reasons. Here is a breakdown of common error codes and potential solutions:

Error Code	Possible Cause	Solution
Bad Request - A required parameter may be missing.	You might have missed to include a mandatory parameter in your webhook configuration.	Double-check your webhook setup and ensure all essential parameters are defined. Refer to your Vertical CRM documentation or the specific external application's API documentation for a complete list of required parameters.
Unauthorized Request - An invalid Auth Token is provided.	The authentication token used in your webhook is either incorrect or expired.	Verify that you have entered the correct Auth Token for the external application. If the token has expired, regenerate a new one according to the external application's instructions.
Request Failed - Parameters were valid but request failed.	It could indicate a temporary glitch in the external application or a configuration issue on your end.	Retry the webhook after a short delay. If the error persists, review your webhook configuration for any mistakes. Additionally, consult the external application's documentation for troubleshooting steps or reach out to their support team.
Page not Found - If the requested item doesn't exist.	The URL specified in your webhook configuration might be incorrect or point to a non-existent resource in the external application.	Carefully review the URL for any typos or errors.
Third-party error - Due to a glitch in the third-party application.	This error happens when there is an issue or a glitch in the third-party application.	Contact the support team of the external application.
Third-party server not available - Disconnection at the third-party API server.	The external application's server might be temporarily unavailable.	Retry the webhook after a while. If the issue persists, contact the external application's support team.
Internal process failure - If there is an error in processing the webhook.	This happens when there is an internal error with the system.	Contact Zoho Vertical Solutions' support for further assistance.
Day limit reached - If the org has reached the maximum limit for the day.	Your organization has exceeded the daily limit for webhook notifications.	Monitor your webhook usage and consider optimizing workflows to reduce the number of unnecessary notifications.
Invalid URL - If the URL is SSRF vulnerable or an invalid URL.	The URL specified in your webhook configuration might be invalid or pose a security risk.	Verify that the URL is a valid address for the intended action within the external application. Ensure it doesn't contain any suspicious elements that could be exploited for security vulnerabilities.
Socket timeout - If the webhook is invoked but response is not received until 10 seconds.	The communication between your Vertical CRM and the third party application might be experiencing a delay.	This could be due to network issues or slow response times on the external application's side. Retry the webhook after a short delay.

Monitoring Webhooks Usage

Vertical Solutions offers valuable tools to help you track and manage your webhook usage within your solutions. Please note that in the developer console, you can view the Sandbox org's usage details.

To view the usage statistics, 

1. Log in to the Zoho Developer Console and navigate to Vertical Solutions.
   
2. Choose the application and select Edit.
   
3. Click on Automate > Workflow > Webhooks
   

The graph in the Webhook home page displays the usage statistics for the past 7 days. Click on the More Info link to get detailed information on usage stats for each day.