Webhooks in Vertical Solutions enable integration with external applications by sending real-time web notifications, along with relevant data,
whenever specified events occur in the solution. By setting up HTTP URLs and linking them to workflow rules, you can streamline the notification process and ensure timely updates across various platforms. For a deeper understanding of Webhooks, visit
webhooks.org.
Here are some examples of how Webhooks can be effectively used in Vertical Solutions:
Automated Invoice Creation: Once a deal is finalized in your Solution, you can transfer customer details to your accounting software to automatically create an invoice.
Email List Management: Automatically add new leads or contacts collected via web forms in your Solution to your email marketing software.
SMS Alerts: Trigger automated SMS notifications to field sales representatives about upcoming meetings, product demos, and other scheduled events.
Estimate Generation: Instantly create an estimate in your accounting system (e.g., QuickBooks) when an opportunity status changes from 'Prospecting' to 'Price Quote'.
Commission Calculation: Calculate and record sales commissions for your team in a commission tracking application (e.g., built on a platform like Zoho Creator) right after a deal is closed in your solution.
How does it work?
Setting Up the notification URL: You'll define a URL within your external application. This URL acts as a special address where your Vertical CRM solution can send notifications.
Connecting the Dots: Within your Vertical solution, you'll create a webhook. This is where you specify the events you want to track (e.g., creating a new lead, updating a deal stage). You'll also provide the URL of the external application (the mailbox we mentioned earlier) where notifications should be sent.
Real-Time Communication: Whenever the chosen event occurs in your Vertical solution (e.g., a new lead is created), a notification is instantly sent to the pre-defined URL in the external application. This notification includes relevant data about the event, such as the lead's contact information,
Taking Action: The external application receives the notification and can then perform an action based on the data it receives. This could involve creating a new record, sending an email, or triggering another automated process.
Setting up Webhooks
Setting up Webhooks involves three steps: creating a webhook, associating it with a workflow rule, and testing the integration.
Step 1 : Create a webhook
- Log in to the Zoho Developer Console and navigate to Vertical Solutions.
- Choose the application you wish to modify and select Edit.
- Click on Automate > Workflow > Webhooks
- Click on Configure Webhook.
- Specify the following:
- Name - Alphanumeric (100): An identifier for your webhook.
- Description - 200 characters : Add a short description for your webhook
- METHOD - Picklist : Select the HTTP method from POST, PUT, GET, DELETE.
- POST allows you to enter the values in the fields of the associated application.
- GET allows you to retrieve information to update in the fields of a record in Zoho CRM
- PUT updates the existing value in the associated application.
- DELETE deletes the existing value in the associated application.
- URL to notify (300 characters) : The URL for the external application, where the notifications are to be sent.
- Module (Picklist): Choose the module. The primary modules like Leads, Accounts, Contacts, Deals, etc are supported, along with Tasks and Meetings.
- 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. - 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.
- 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.
- 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.
- 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.
- Module Parameters : Add the Parameter name, type, and value from the dropdowns.
- Custom Parameter : Add the parameter name and value.
- 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 #.
- 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.
- 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.
- Click on Save
Please note the following:
- When the Request Method is set to POST or PUT, the configuration options for Header and Body are displayed.
- If the Request Method is set to DELETE, the options for Header and Form-Data in the body configuration are displayed.
- For a Request Method set to GET, only the body configuration in form-data format is visible.
- In the Meetings module, it is not possible to utilize personal details of participants like Email, Phone, Mobile, etc., as parameters in a webhook.
Step 2: Associate the webhook with a workflow
By associating a webhook with a workflow rule, you can define the exact triggers that will initiate the webhook notification. You can automate tasks such as sending notifications, updating records, and triggering actions in external systems based on specific events within your solution.
To associate a webhook to a workflow rule,
- Log in to the Zoho Developer Console and navigate to Vertical Solutions.
- Choose the application you wish to modify and select Edit.
- Click on Automate > Workflow > Rules
- Click on Create Rule. In the Create New Rule pop-up, specify the following details and click Next.
- Module : Choose the module from the dropdown
- Rule Name : Specify an identifier for the rule
- Description
- Define the workflow rule as per your requirement.
- In the Instance Action section, select webhook to associate a webhook with the rule.
- From the listed webhooks, select the webhook. Please note that you can also create a new webhook from this page, by clicking on + New Webhook at the top right window.
- Click on Associate
Step 3 : Test the webhook integration
Once you have associated your webhook with a workflow rule, you must ensure that everything functions as intended.
- Craft Test Data: In your solution sandbox environment, create new data entries that meet the criteria defined in your workflow rule. This could involve creating a new lead, updating a deal stage, or any other action that should trigger your webhook notification.
- Monitor Your Application: Head over to your external application and keep an eye out for data received from your solution via the webhook notification.
- Scrutinize for Accuracy: Once you receive the data, compare it to the test data you created in your CRM. Ensure all the information matches up perfectly.
- Refine and Repeat: If you encounter any errors or inconsistencies in the data, revisit your webhook settings in the developer console. Double-check the URL, parameter configurations, and any other relevant details. Then, repeat steps 1-3 to retest the integration with your corrected settings. When you consistently receive accurate data from the solution in your external application upon triggering your workflow rule, you have successfully established a functional webhook integration.
Step 4 : Publish the solution and upgrade your customers
After you have successfully tested the webhook integration and ensured that all automated processes are functioning correctly, the next step is to publish the solution and upgrade your customers.
Webhook Association Limits:
Per workflow rule, you can associate up to 6 webhooks: 1 Instant Action and 5 Time-Based Actions.
Data Transfer Limitations:
- Headers: Up to 10 header parameters (including module and custom fields) can be included.
- Body:
- Form-Data: Supports a maximum of 25 module parameters, 10 custom parameters, and a structured parameter with a 10,000-character limit.
- Raw Data: Accommodates up to 15,000 characters. Choose one type (Form-Data or Raw) per webhook.
![](https://static.zohocdn.com/zoho-desk-editor/static/images/file.png)
Important Notes:
- Data retrieval from external apps to the solution is not possible.
- Regularly update the API ticket according to the limits set by third-party applications. to avoid disruptions.
- You will not receive email notifications if the webhook integration stops functioning due to an issue in a third-party API.
- 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.
- 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.
- In the URL to Notify field, you can specify port numbers. Please note that only ports 80 and 443 are supported.
- Vertical Solutions provides an option to select the required Date/Date Time format and Time Zone during webhook parameter configuration.
- Limits for Webhooks is 500,000 calls/day or 500 calls/user/day (whichever is lower).
Troubleshooting Unsupported Merge Fields in Webhooks
Ever created a webhook in your solution, only to see some merge field values displayed as ${Unsupported_Field}? Here is why you might encounter this issue:
- 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.
- 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.
- 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:
- Conduct periodic reviews of your webhooks to identify and update any outdated merge field references.
- Verify that the chosen merge fields align with the specific module you are working within.
- 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,
- Log in to the Zoho Developer Console and navigate to Vertical Solutions.
- Choose the application and select Edit.
- 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.
In addition to the usage statistics, you can also view the List of Webhooks on the home page. There is also a log of webhook failures, including detailed reasons for each failure.