
Hello all!!
Welcome back to a fresh Kaizen week.
This week, we will continue with another Actions API -
Webhooks API in Zoho CRM.
Webhooks in Zoho CRM
A webhook allows Zoho CRM to send real-time information to another application the moment something important happens. Webhooks let CRM push data instantly to an external URL whenever the workflow condition is met.
Webhooks do not notify on every record event by default. They trigger only when specific automations, such as a Workflow Rule you configure, are executed. This helps for specific real-time automation needs, such as sending high-value leads to an external validation service.
Use case
Zylker, an IT solutions provider, uses Zoho CRM to manage all incoming leads. But not every new lead is ready for the Sales team right away. Not all leads need immediate follow-ups. For leads with a high Profit Score (80+), it usually means strong buying intent, but they may contain fake information.
Why does Zylker use Zoho CRM and send these leads to an external validation application?
Before Sales reaches out, Zylker wants to make sure these high-value leads have valid information. While CRM keeps the lead data organized, a specialized third-party validation systems check any fraudulent activities and confirm whether the email, phone number, or other details are real.
To do this quickly, Zylker uses Webhooks in Zoho CRM. The moment a lead crosses the 80+ score, Zoho CRM automatically sends the lead’s data to Zylker’s external validation system. This lets Zylker verify the lead in real time and send back a clean, accurate, sales-ready profile for the Sales team to follow up on.
From here, we will explain every part of Webhooks by showing how it looks in the Zoho CRM UI and how to do the same using the API. Each step will be shown side-by-side, so you can clearly see how the UI setup translates into the API request.
Configuring Webhooks for Zylker’s Use Case - UI Method
- Go to Setup
- Navigate to Automation
- Choose Actions -> Webhooks
- Click Configure Webhook
You will see the window shown below.
Webhook - UI view
The following sections explain what each field means in three parts:
- Basic fields to configure Webhook.
- Configuring Headers
- Configuring Body
Filling the basic Webhook details via UI
Filling the basic Webhook details via Create Webhook API
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { "name": "Push High Score Leads", "description": "Send leads with Profit Score > 80 to validation system.", "module": { "api_name": "Leads", "id": "5725767000000002175" }, "authentication": { "type": "general" }, "http_method": "POST" } ] }
|
Keys explanation
- name (mandatory): Name of your webhook.
- description: Add a short note about what this webhook does.
- module (mandatory): Select the module from where the external application listens the changes. In our case, select Leads module to push high-score leads.
- url (mandatory): Specify the external endpoint where CRM will send the data. This lets the external application see what CRM sends.
- Note: In this post, we have used an endpoint from Webhook.site
- authentication (mandatory): Specify authentication type for the webhook endpoint.
- Possible types:
- general: The receiving system does not require OAuth. You can pass OAuth tokens manually in headers.
- connections:
- OAuth-based integrations: Systems that use Zoho’s Connections.
- For our Zylker use case, we select General.
Note: In
Zoho CRM API V8, Webhooks currently support only General authentication. Connection-based authentication will be available in a future update.
- http_method (mandatory): Select a HTTP method that allows you to send structured data.
Possible values: POST, GET, PUT, DELETE
In our case, we use POST to create a new record in the external app with the necessary lead details, allowing the external system to run its validation checks.
HTTP methods and their supported parameters - Headers, Body, URL Parameters
HTTP Method | Headers | Body | URL Parameters |
POST | Module parameters Custom parameters
| Type: form-data
Module parameters Custom parameters User-defined parameters
Formats: null
Type: raw
Formats: Text, JSON, HTML, XML | Not Supported |
PUT | Module parameters Custom parameters
| Type: form-data
Module parameters Custom parameters User-defined parameters
Formats: null
Type: raw
Formats: Text, JSON, HTML, XML | Not Supported |
GET | Not Supported | Not Supported | - Module parameters
- Custom parameters
- User-defined parameters
|
DELETE | Not Supported | Not Supported | Module parameters Custom parameters User-defined parameters
|
Each HTTP method supports different parameter types. The above table shows which methods support Headers, Request Body, and URL Parameters. Detailed explanations of these parameter types are provided in the following section.
Creating a Webhook with Headers, Body, and URL Parameters
When a webhook is triggered in Zoho CRM, the data is sent to the external application as part of the HTTP request.
The data can be sent in three places:
- Headers
- Body (Form-Data or Raw)
- URL Parameters
Each part serves a different purpose.
Configuring Headers
UI - Configuration

Headers allow you to send
extra information along with your webhook request. These help when the external app needs extra data like auth tokens or CRM field values.
Zoho CRM supports two types of headers:
- Module Parameters - Dynamic values from CRM fields
- Custom Parameters - Static values you define
Module Parameters - dynamic CRM data
Module parameters allow you to send values from CRM fields inside the header. These values change depending on the record that triggered the webhook.
A module parameter consists of:
- Parameter Name - A unique header key that you define. It does not have to match the CRM field API name.
- Parameter Type - Defines the source of the data you are mapping. It can come from the selected CRM module such as Leads and Contacts, lookup fields, User fields such as Lead Owner, or Organization fields.
- Parameter Value - The merge field value. Example, ${!Leads.Created_By.id}
Note: If you decide to use Headers, then you must add at least one module_parameter. Otherwise CRM will show an error.
Example:
Parameter Name | Parameter Type | Parameter Value |
Lead_Email | Leads | Email |
Annual_Revenue | Leads | Annual Revenue |
Profit_Score | Leads | Profit Score |
Created_By | Created By | User Id |
Custom Parameters - static values
Custom parameters are key-value pairs that never change.
These are useful for:
- API version
- Tags like “zylker-crm”
Name | Value |
source | zylker-crm |
version | v1 |
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { . . . "http_method": "POST", "headers": { "module_parameters": [ { "name": "Lead_Email", "value": "${!Leads.Email}" }, { "name": "Annual_Revenue", "value": "${!Leads.Annual_Revenue}" }, { "name": "Profit_Score", "value": "${!Leads.Profit_Score}" }, { "name": "Created_By", "value": "${!Leads.Created_By.id}" } ], "custom_parameters": [ { "name": "source", "value": "zylker-crm" }, { "name": "version", "value": "v1" } ] } } ] }
|
When should Zylker use Headers?
For the 80+ Profit Score validation use case, Zylker can include module parameters such as Lead Email, Profit Score, and Lead ID, which are helpful for fraud-detection tools.
Similarly, Zylker can include custom parameters like source=zylker-crm and api_version=v1 to help the external system identify where the webhook originated.
Configuring the Body of a Webhook - form-data & raw formats
After setting up the basic details and Headers, the next step is to configure the Body.
The Body is where the main CRM record data is sent, which is different from the Header section that only carries metadata like auth tokens or quick identifiers.
Depending on your needs, the Body can be either Form-Data or Raw. The list below shows the supported options for each format.
- Form-Data:
- Module parameter
- Custom parameter
- User-defined format.
- Raw:
- Text - plain messages
- JSON - structured API payload
- HTML - formatted messages
- XML - traditional enterprise systems
Form-Data Body: key-value
UI - Configuration
Zoho CRM lets you build Form-Data using three types of parameters:
- Module Parameters
- Custom Parameters
- User Defined Parameters
Use Form-Data when the external app expects key-value pairs - similar to how HTML forms submit data.
Note:
- Headers are for sending supporting information that helps the external system understand the request - this can include auth details, source identifiers, or key CRM fields like email or score that help with quick categorization or filtering.
Why do Module and Custom parameters appear again in Form-Data?
The same Module Parameters and Custom Parameters are available in the Body because:
- Headers - Provide supporting details such as identifiers or quick-check values. For example, Lead ID, or source tags that help the external system check and route the request.
- Body - Contains the complete lead information that the external validation system needs to process.
Although the parameter names look the same (Module, Custom), their purpose changes:
Where parameters are used | Purpose | Example |
Headers | Metadata - OAuth,tags, and context | source: zylker-crm |
Form-Data (Body) | Main record data - actual lead details sent to the app. | lead_email=patricia@zylker.com |
So Zoho CRM gives you the same structure, but used differently depending on where the data is placed.
User-Defined Parameters
User-Defined parameters let you build custom, human-readable messages or templates. This parameter is available only in the Body, not in Headers.
Parameter Name | Parameter Value |
custom_message | New high-score lead: ${Leads.First Name}${Leads.Last Name} (Score: ${Leads.Profit Score}) |
This is very helpful if your external app expects a text message, notes, or a description field.
Configuring the Body of a Webhook - form-data via Create Webhook API
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { . . . "body": { "form_data_content": { "module_parameters": [ { "name": "Lead_Email", "value": "${!Leads.Email}" }, { "name": "Annual_Revenue", "value": "${!Leads.Annual_Revenue}" }, { "name": "Profit_Score", "value": "${!Leads.Profit_Score}" }, { "name": "Created_By", "value": "${!Leads.Created_By.id}" } ], "custom_parameters": [ { "name": "source", "value": "zylker-crm" }, { "name": "version", "value": "v1" } ], "user_defined_parameters": { "name": "custom_message", "value": "New high-score lead: ${!Leads.First_Name}${!Leads.Last_Name} (Score: ${!Leads.Profit_Score})" } }, "type": "form_data" }, . . . } ] }
|
Raw Body - JSON / XML / HTML / Text
Zoho CRM’s Webhook Body section allows you to send data to an external application in a Raw format. This is useful when the receiving system expects structured data in the following structure.
You can choose:
- Raw + Text
- Raw + JSON
- Raw + HTML
- Raw + XML
Raw + Text:
Text format is the simplest. You can type any text and insert merge fields.
UI - Configuration
When to use Text?
- When sending a simple message.
- When the external app only expects plain text.
Configuring the Body of a Webhook - Raw - "Text" via Create Webhook API
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { . . . "body": { "raw_data_content": "New high score lead: ${!Leads.First_Name} ${!Leads.Last_Name}, ${!Leads.Email}, ${!Leads.Annual_Revenue}, ${!Leads.Phone}, ${!Leads.Industry}, ${!Leads.Owner}", "format": "Text", "type": "raw" }, . . . } ] }
|
Raw + JSON:
This is the most common format for APIs. Use this when the receiving system expects structured JSON data.
UI - Configuration
Configuring the Body of a Webhook - Raw - "JSON" via Create Webhook API
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { . . . "body": { "raw_data_content": "{\n \"id\": \"${!Leads.id}\",\n \"full_name\": \"${!Leads.Last_Name}\",\n \"email\": \"${!Leads.Email}\",\n \"company\": \"${!Leads.Company}\",\n \"profit_score\": \"${!Leads.Profit_Score}\",\n \"owner\": \"${!Leads.Owner}\"\n}", "format": "JSON", "type": "raw" }, . . . } ] }
|
When to use JSON?
- When the external system expects structured data
- Easier validation
Raw + HTML:
HTML format is useful for sending stylized messages or formatted content.
UI - Configuration
Configuring the Body of a Webhook - Raw - "HTML" via Create Webhook API
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { . . . "body": { "raw_data_content": "<p><strong>New Lead Alert</strong></p>\n<p>Name: ${!Leads.Last_Name}</p>\n<p>Email: ${!Leads.Email}</p>\n<p>Company: ${!Leads.Company}</p>\n<p>Profit Score: ${!Leads.Profit_Score}</p>\n<p>Owner: ${!Leads.Owner}</p>", "format": "HTML", "type": "raw" }, . . . } ] }
|
When to use HTML?
- If the external system displays formatted output
Raw + XML:
Some legacy systems or enterprise applications prefer XML.
UI - Configuration
Configuring the Body of a Webhook - Raw - "XML" via Create Webhook API
Request URL: {{api-domain}}/crm/v8/settings/automation/webhooks
Request Method: POST
Input JSON
{ "webhooks": [ { . . . "raw_data_content": "<Lead>\n <Id>${!Leads.id}</Id>\n <Name>${!Leads.Last_Name}</Name>\n <Email>${!Leads.Email}</Email>\n <Company>${!Leads.Company}</Company>\n <ProfitScore>${!Leads.Profit_Score}</ProfitScore>\n<LeadOwner>${!Leads.Owner}</LeadOwner>\n</Lead>", "format": "XML", "type": "raw" }, . . . } ] }
|
When to use XML?
- With older systems
- When the receiving system only supports XML
Note:
- When you switch the webhook method in the UI, Zoho CRM changes the options you can configure:
GET Method
- Only URL Parameters are available
- Headers are hidden
- Body is hidden
- Because GET requests always send data through the URL and cannot carry a body.
DELETE Method
- Headers are available
- URL Parameters are available
- Body is still not supported
- DELETE requests can include headers, but Zoho CRM does not allow sending a body for DELETE webhooks.
- Date-time format:
Zoho CRM will format any Date or DateTime fields in your webhook according to the format you select.
UI - Configuration
API - Configuration
{ "webhooks": [ { "module": { "api_name": "Leads", "id": "5725767000000002175" }, "url_parameters": { "module_parameters": [ { "name": "Created_Time", "value": "${!Leads.Created_Time}" } ] }, "description": "Send leads with Profit Score > 80 to validation system.", "http_method": "GET", "name": "Push High Score Leads", "date_time_format": { "datetime_format": "mm-dd-yyyy HH:MM:SS", "date_format": "yyyy-mm-dd", "time_zone": "America/Los_Angeles" }, "authentication": { "connection_name": null, "type": "general" } } ] }
|
With this, we have covered what a
Webhook is in Zoho CRM, how to configure a basic Webhook, how to configure a Webhook with Headers, Body, and URL Parameters, how each component works, how to configure them using the UI, and how the same setup can be created through the
POST Webhooks API.
In Part 2, we will explain
- How to manage Webhooks using the GET, PUT, and DELETE Webhook APIs
- How to associate a Webhook with a Workflow
- How to perform real-time testing by creating records
- How an external application receives data from Zoho CRM via Webhook.
We hope this post helps you understand how to use Webhooks through the Zoho CRM Actions API -
Webhooks API.
Try it out, and let us know your experience in the comments section or reach out to us at
support@zohocrm.com.
Stay tuned for more insights in our upcoming Kaizen posts!
Cheers!
Recent Topics
How to calculate separate totals for Product Line Items filtered by category in Quotes?
Hello! I'm working with Quotes in Zoho CRM and need help calculating conditional totals for line items. Current setup: I have two tables in my Quote template (Zoho Writer), both displaying Quoted Line Items Table 1 (top): Shows all products where Product
I Need Help Verifying Ownership of My Zoho Help Desk on Google Search Console
I added my Zoho desk portal to Google Search Console, but since i do not have access to the html code of my theme, i could not verify ownership of my portal on Google search console. I want you to help me place the html code given to me from Google search
Zoho Desk API Documentation missing a required field
We are trying to create a section using this information. Even after preparing everything based on that page, we still get an error. The error we get is this: {"errorCode":"INVALID_DATA","message":"The data is invalid due to validation restrictions","errors":[{"fieldName":"/translations","errorType":"missing","errorMessage":""}]}
Fetch Subform values through a lookup of a lookup
Hi, I'm having an issue fetching the values of a subform through a lookup field through another lookup field. The code works perfectly to show me the subform row ID, but the second I try to get any readable data, it says "Error occurred. Please contact
Turn Decision Box to a button
Dear all, I need your help on CSS to turn a Decision Box to a Button. I have a Decision Box like: Turn on/off to refresh the information. (on User Input, either True or False, will refresh the information) Now I want to simulate to treat it like a Refresh
Emails not being received from a particular domain
Cannot receive any emails sent from atco.com Domain is in the spam whitelist so should be no reason for it not to be coming through. Have filed a ticket and besides a generic response of we are looking at it - it seems there is no actual support workers
Stock Count
The stock count is a nice new feature, but we cannot figure out how to: 1. Use it without assigning to a person, we have a team or one of multiple do stock counts as do most any company. 2. Add any extra fields to what the "counter" sees. The most important
Can you import projects into Zoho Projects yet?
I see some very old posts asking about importing project records into Zoho Projects. But I can't find anything up to date about the topic. Has this functionality been added? Importing tasks is helpful. But we do have a project where importing projects
How to delete attachments form Zoho mail accounts
I can't find a way to delete attachments from Zoho mail messages, either individually or in bulk. Searches here are providing conflicting results and often talk about workspace, whereas I am only interested in how to delete attachments that are seen with
Send Whatsapp message from Whatsapp template with custom variables
Hi, I'm trying to do some basic integration for sending WhatsApp messages from Zoho CRM using Zoho Desk whatsapp templates. When creating new whatsapp template in Zoho Desk we can choose ticket related fields as variables but it's not clear how to use
Outgoing blocked: Unusual activity detected.
I just made payment for my Zohomail Today and have been debited so i will like to be Unblocked because this is what it says (Outgoing blocked: Unusual activity detected) Thank you i await your swift responses
Integrating with My Own Application and ZOHO CRM Simultaneously
I have my own WhatsApp bot that uses my WhatsApp business account. I want to use the same phone number to integrate with ZOHO as well. What is the recommended way to do that? Should I integrate my application with ZOHO, forwarding messages whenever the
How do i move multiple tickets to a different department?
Hello, i have several tickets that have been assigned to the wrong department. I am talking about hundreds of automatically generated ones that come from a separate system. How can i select them all at once to move them to another department in one go? I can select them in "unsassigned open tickets view" but i can't find a "move to another department" option. I also can't seem to assign multiple tickets to the same agent in that same view. Could somebody advice?
Transferring CRM Attachments to Workdrive
relatedrecords = zoho.crm.getRelatedRecords("Attachments","Conditions",conId); attachid = List(); for each ele in relatedrecords { attachementId = ele.get("id"); attachid.add(attachementId); } for each ele in attachid { counter = 1; downloadFile = invokeurl [ url: "https://www.zohoapis.com/crm/v2/Conditions/" + conId + "/Attachments/" + ele type: GET connection : "work_drive" ]; resp2 = zoho.crm.attachFile("Deals",dealId,downloadFile); resp3 = zoho.workdrive.uploadFile(downloadFile, dealWD, "PlaceHolder"+counter+"",
New Customization options in the module builder: Quick Create and Detail view
Hello everyone, We have introduced two new components to the module builder: Quick create and Detail view. The Quick Create Component It is a mini form used to create a record and associate it to the parent record from a lookup field. For example, if you have a Deals lookup in the Contacts module, then you can associate existing deals or create a deal and associate it with the contact. You can customize this Quick Create form by adding standard as well as custom fields. There is no limit to the number
unblock my zoho mail account. outlines@zoho.com
please unblock my zoho mail account, outlines@zoho.com
SMTP email sending problem
Hello, I've sent emails before, but you haven't responded. Please respond. My work is being disrupted. I can't send emails via SMTP. Initially, there were no problems, but now I'm constantly receiving 550 bounce errors. I can't use the service I paid
Mailk got blocked / Inquiry About Email Sending Limits and Upgrade Options
Dear Zoho Support Team, My name is Kamr Elsayed I created this account to use for applying for vocational training in Germany. As part of this process, I send multiple emails to different companies. However, after sending only 8 emails today, I received
Forwarder
Hi, I tried to add a forwarder from which emails are sent to my main zoho account email . However, it asks me for a code that should be received at the forwarder email, which is still not activated to send to my zoho emial account. So how can I get the
No chat option
Chat option is not supported.
Direct “Add to Google Calendar” Option in Zoho Meeting
Hello Zoho Meeting Team, Hope you are doing well. We would like to request an enhancement related to the “Add to Calendar” functionality in Zoho Meeting. Currently, when we open Zoho Meeting and view our meetings under My Calendar, there is an Add to
Default Tagging on API-generated Transactions
If one assigns tags to an Item or Customer, those tags get auto-populated in each line item of an Invoice or Sales Order when one creates those documents. However, if one creates the Sales Order or Invoice via the API (either directly coding or using
DKIM cannot be enabled for the domain as no verified default selector present
Hi Support Team, For Domain DKIM record trying to enable status. but showing error "DKIM cannot be enabled for the domain as no verified default selector present" So, please resolve the issue. Thank you.
unable to send message reason 554 5.1.8 Email outgoing blocked
unable to send message reason 554 5.1.8 Email outgoing blocked
I can't log in to my account on Thunderbird
I've just had to rebuild my PC (calamitous mess from Microsoft with Win10/Win 11 'upgrade' - they confirmed I had to start with a new build). I have used Zoho mail for years via Mozilla Thunderbird, but now I've had to download the latest version of TBird,
Should I Use DMARC?
When I configure Zoho Mail's DMARC settings, it's mandatory to fill in the RUA and RUF (Aggregate notification email address*, Forensic notification email address*) addresses. When we enter an email address in these fields, we receive reports from the
Introducing Profile Summary: Faster Candidate Insights with Zia
We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiring
Books API Receiving an Error that Doesn't Make Sense when Creating Credit Note - trying to use 'ignore_auto_number_generation' argument
Hello, I'm working on a newly created routine and I'm getting an error that doesn't make sense when trying to create a new Credit Note. Here is my POST request. Endpoint: https://www.zohoapis.com/books/v3/creditnotes?organization_id=########## Body: {
How to move emails to Shared Mailbox?
Hello, I created a Shred Mailbox instead of using a distribution group. But I cannot move previous emails to certain shared mailbox. Is it possible move some emails from inbox to shared mailbox?
Collaboration with free plan user.
Hello. Do both users need to be on Pro plan to collaborate? Or can a Pro user share a note with a free plan user with the ability to edit?
Connection to other user
Zoho Cliq handles sharing of Custom OAuth Connections that require individual user logins.
In arattai received message can't be deleted
The issue has been noticed in following: arattai app (Android) arattai app (Window) arattai web While the message posted by me may be deleted, the ones received from others can't be. The item <Delete> change to <Report> when the message is a received
Analytics Portal
I have the "standard plan" and want to explore the portal option; I activated the 15-day trial but do not see the pricing for the add-on. How can I get the price under "Upgrade add-ons." Thanks Rudy
Can I filter a Lookup field to only show related records from another Lookup in Zoho CRM?
In our Leads module, we have two Lookup fields: Recruitment Agency – the agency that the lead came from Recruiter – the individual contact from that agency who sent us the lead Both fields link correctly to their respective records in CRM. However, our
Zoho Books API invoice email bouncing with 'relaying-issues' error
I have waited over 30 days for zoho books uk to assist with the following and i have had no replies or tickets erronously closed. The service has been terrible - very unlike zoho! So i am raising this here hoping that a community member can assist: Hello,
How do I filter contacts by account parameters?
Need to filter a contact view according to account parameter, eg account type. Without this filter users are overwhelmed with irrelevant contacts. Workaround is to create a custom 'Contact Type' field but this unbearable duplicity as the information already
Zoho Writer to Zoho Sign Template Misalignment – Request for Community
We are currently facing a critical issue impacting our live business operations due to a misalignment problem between Zoho Writer templates and Zoho Sign output. Issue Summary: We have an automated workflow in Zoho CRM using Deluge scripts that generates
Account blocked
Yesterday I got my Zeptomail account blocked due to too many hard bounces. My account is used exclusively for sending transactional emails (eg. your order has been shipped, a form has been filled, etc) and the sudden blocking impacted hundreds of websites
Migration Tool Download
Since apparently you have to ask for the migration tool to download (why?), I need the download for the migration tool for exchange servers. Please forward link, thanks.
IF Formula
Hi, I'm having trouble setting up a custom formula in a field. Can you help me with it? The formula should do the following: If the created date is less or equal to 30 days the field should display a string New in pieline or Exisitng pipeline if above
Next Page