Webhooks

List of Fields in Webhook

Set Up Webhooks

Setting up Webhooks includes the following three steps:

• Create a webhook.
• Associate webhook to a workflow rule.
• Test webhook integration.

To create a webhook

1. Click Setup > Automation > Workflow > Webhooks.
2. In the Webhooks page, click the Configure Webhook.
3. In the Configure Webhook page, specify all necessary parameters.
4. Click Save.

To associate webhook to a workflow rule

1. Click Setup > Automation > Workflow Rules.
2. In the Workflow Rules page, click the Create a Workflow Rule.
3. In the Workflow Rule page, specify workflow rule parameters.
4. Under Workflow Actions, select the webhooks to be triggered.
5. Click Save.

To test the webhook integration

1. Add test data in CRM according to your workflow rule criteria.
2. In your application check for the data received from Zoho CRM via webhook notification.
3. If there is an error or data mismatch, modify your webhook settings in Zoho CRM.
4. Continue this test until you obtain the required data from Zoho CRM to your Application.

Important Notes

• You can associate up to 6 (1 Instant Action and 5 Time-Based Actions) webhooks per workflow rule.
• You can transfer data for a maximum of 10 CRM fields from Zoho CRM to third-party applications using webhook.
• You cannot retrieve data from other Apps to Zoho CRM using webhooks.
• You must update the API ticket regularly according to limits in third-party applications.
• You will not receive any email notification, if the Webhook integration stopped functioning due to any issue in a third-party API.
• If there is any failure in the process, Webhook will send a notification first, Zoho CRM system will send a second notification after 15 min. Thereafter, the system will not send any Webhook notifications for that particular workflow trigger.
• If you exceed the maximum count per day, the system will not send remaining Webhook notifications to third-party applications and will notify thw failure to Administrator. 
• Zoho CRM will the send the data in following standard format for Date and Date Time fields to third-party applications:
  • Date: yyyy-MM-dd
  • Date Time: yyyy-MM-dd hh:mm

Business Scenario 1

Calculate Sales Commission in Zoho Creator App upon closing an Opportunity in Zoho CRM.

Purpose

Sales Managers and the Payroll team can use the Sales Commission app to calculate the compensation for your Sales Reps according to a pre-defined formula set by your organization (for example, flat 2% of the closed contract or sales amount). This application helps you to reduce manual entries, minimize errors and save time while calculating commission for your Sales Reps. Additionally, Sales Reps can track their monthly commissions in a central location.

Pre-requisite

• Account in Zoho Creator Application
• Permission to access Zoho API
• Familiarity with Zoho Creator

Procedure

1. Create the Sales Commission App in Zoho Creator (Refer Zoho Creator Tutorial on Creating Apps)
2. Configure webhook in Zoho CRM
3. Set up Workflow Rule
4. Test your webhook integration

Step 1: Create Sales Commissions App in Zoho Creator

In Zoho Creator, create the Sales Commission App with following fields:

• Sales Rep
• Potential Name
• Customer Name
• Opportunity Amount
• Type of Business: New Business or Existing Business
• Closing Date
• Sales Commission

To create an Application in Zoho Creator refer to the online help

Step 2: Configure Webhook

Select the following Fields from the Potentials module while setting up user-defined parameters:

• Potential Name
• Closing Date
• Type
• Record Owner
• Amount

In Webhook, specify the following details:
URL to Notify:

1. https://creator.zoho.com/api/xml/write - POST method

User-defined Parameters (XML or JSON)

Custom Parameters:

Step 3: Set up Workflow Rule

Follow these steps in the Workflow Rule page:

1. Set up workflow criteria as:
   • Type is New Business
   • Stage is Closed Won
2. Select the webhook as an instant action.
3. Save workflow rule.

Workflow Rule Criteria

Associate Webhook to Workflow Rule

Step 4: Test your Integration

1. Add a test potential in CRM with Type and Stage fields as a New Business and Closed Won respectively. While entering test data, ensure that Amount, Closing Data, Record Owner, Account Name and Potential Name are also entered.
2. Open your Sales Commission App in Zoho Creator and check for the CRM data. 
   If you've not received any data, modify the webhook configuration and continue testing. After successful testing, remove test entries and roll-out this integration to your CRM users.

Business Scenario 2

Send SMS alerts to customers and sales reps.

Purpose

A payment from a customer is due today. You can send an SMS with the payment due date, customer name, and amount details to your Sales Rep by associating webhook to time-based action in workflow rule.

Pre-requisite

• Account in SMS gateway service
• Permission to access Workflow Rules

Procedure

1. Create an account in SMS gateway service
2. Configure webhook in Zoho CRM
3. Set up Workflow Rule
4. Test your webhook integration

Step 1: Create an account in SMS gateway service

In your SMS gateway service, create an account and get these details to configure webhook:

• Sales Rep
• Potential Name
• Customer Name
• Opportunity Amount
• Type of Business: New Business
• Stage: Closed Won
• Payment Due Date (custom field)

Currently Zoho has partnered with the following SMS Gateway providers:

• Bulk SMS
• Clickatell
• Screen Magic
• Valueleaf

You can buy SMS credits and API details from the above vendors.

Step 2: Configure Webhook

Select the following Fields from the Leads module while setting up user-defined parameters:

• IP address of SMS gateway
• Username
• API key

In webhook, specify the following details:

URL to Notify:

1. http://<IP Address>/smsgateway/post - POST method

User-defined Parameters (XML or JSON)

Step 3: Set up Workflow Rule

Follow these steps in the Workflow Rule page:

1. Set up workflow criteria as:
   • Type is New Business
   • Stage is Closed Won
2. Select the webhook as a time-based action.
3. Save workflow rule.

Workflow Rule Criteria

Associate Webhook to Workflow Rule

Step 4: Test your Integration

1. Add a test potential in CRM with Type and Payment Due Date fields as a Existing Business and Today respectively. While entering test data, ensure that Amount, Closing Data, Record Owner, Account Name and Potential Name are also entered.
2. In your mobile phone check for the SMS alert
   If you've not received SMS, modify the webhook configuration and continue testing. After successful testing, remove test entries and roll-out this integration to your CRM users.

---

Refer Error Codes

When execution of webhook fails, one of the following error messages are displayed in Zoho CRM:

HTTP Status Codes

• 400 Bad Request - Often missing a required parameter.
• 401 Unauthorized - No valid API key provided.
• 402 Request Failed - Parameters were valid but request failed.
• 404 Not Found - The requested item doesn't exist.
• 500, 502, 503, 504 Server errors - Something went wrong on third-party application.
• Error Code 1 - Temporarily not able to connect to the API server. You need to check API server logs, firewalls settings for our requests sent from CRM.

Custom Errors

• Internal process failure - When the webhook is not executed due to errors in processing the webhook.
• Day limit reached - When the company reached the maximum limit for the day.