Create Webhook

Webhooks in Zoho CRM allow you to send real-time data from Zoho CRM to external applications or services when specific events occur such as Record creation, update, or deletion.

Purpose

Configure a webhook in your Zoho CRM account.

Endpoints

POST /settings/automation/webhooks

Request Details

Request URL

{api-domain}/crm/{version}/settings/automation/webhooks

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.automation_actions.CREATE
(or)
ZohoCRM.settings.automation_actions.ALL
(or)
ZohoCRM.settings.ALL

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/webhooks"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@webhook.json"
-X POST

Input JSON

webhooksJSON array, mandatory

Object containing the webhook configuration details.

modulestring, mandatory
Specify the module such as Leads or Contacts where the webhook should listen for changes. When a record in this module triggers the webhook, the related data will be sent to the external application or service.
Use the Get Modules Metadata API to get the module API name and ID.
Note: You can not set up webhooks for Call Logs and Notes modules.
namestring, mandatory
Specify a unique name for the webhook.
urlstring, mandatory
Specify the endpoint URL where Zoho CRM must send the webhook data. This is the external address that will receive the webhook request when triggered.

http_methodstring, mandatory

Specify the HTTP method that must be used to send the webhook request.
The support for Headers, Body, and URL Parameters varies based on the HTTP method used. Refer to the following table for details.

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

descriptionstring, optional
Specify a brief description of what the webhook does or its purpose. This helps you and others understand the function or intent of the webhook when managing multiple webhooks.
authenticationJSON object, mandatory
Specify authentication details for the webhook endpoint.
- typestring, mandatory
  Specify the authentication method.
  Possible values:
  - general : To configure the webhook with no authorization, basic authorization or API authorization.
- headersJSON object, optional
  Headers let you send extra information along with the webhook request. For example, API keys, authentication tokens, or custom values that the external application needs.
  You can add both dynamic data from Zoho CRM as module parameters and your own custom values as custom headers.
  This key is applicable only for POST and PUT requests.
  Possible headers: module_parameters, custom_parameters
- module_parametersJSON array, optional (optional by default, if you want to include headers key, then the module_parameters key is mandatory)
  These are dynamic values taken from fields in the selected module. These change based on the record that triggers the webhook.
  Specify the following:
  - name - Specify a unique header name. Please note that if you choose Headers, you must add at least one module parameter with a value. If you do not add it, the system will show an error when you try to save the webhook.
  - type - Specify a source type of the parameter where the fields come from.
    - Possible parameter type options: CRM modules such as Leads and Contacts, Users, Organization, and the available lookup fields in the module.
  - value - Specify a value of the module header, specified using the merge field format. Example, ${!Leads.Email}.
  For example, Emails in the Leads module. Use the Get Fields Metadata API to retrieve field API names.
- custom_parametersJSON aray, optional
  These are static values that never change. They are always sent with the webhook call.
  - namestring, optional
    Specify a name to the custom header.
  - valuestring, optional
    Specify a value to the custom header.
```
"custom_parameters": [
    {
        "name": "OAuth",
        "value": "2.0"
    }
]
```
- user_defined_parametersJSON object, optional
  Users can format their data in their own way using merge fields i.e., it allows users to format and send custom or templated data using merge fields.
  - namestring, mandatory
    Specify a unique name to the user defined parameter.
  - valuestring, mandatory
    Specify a value to the user defined parameter.
```
"user_defined_parameters": 

{
"name": "custom_message",
"value": "New lead created: ${!Leads.First_Name}${!Leads.Last_Name} ${!Leads.Email})"
}
```
bodyJSON object, optional
Define the data that Zoho CRM sends in the body of the webhook request. This is applicable only for POST and PUT HTTP methods.
1. Raw Body (Sent in Body)
Use this when you want to send plain text, JSON, HTML, or XML content directly.
Body type is raw ("type" : "raw")
```
{
     "body": {
     "type": "raw",
     "format": "Text", //Possible values: Text,JSON, HTML, and XML
     "raw_data_content":"Hello Webhooks!"
   }           
}
```
2. Form Data (Sent in Body)
Use when you want to send data as key-value pairs in the body of the webhook request, like form submissions.
The data can be pulled from:
- module_parameters (mandatory) : Pull dynamic values from CRM fields. Example, ${!Leads.Email}
- custom_parameters : You can manually specify any static values. Example, "API_version": "v2"
- user_defined_parameters : You can define any predefined content or templated content. Example, "message": "Webhook for ${!Leads.Last_Name}"
Body type is Form data ("type" : "form_data")
```
{
     "body": {
     "type": "form_data",
     "format": null,
     "form_data_content": "module_parameters", //Possible values: module_parameters, custom_parameters, and user_defined_parameters
   }         
}
```
url_parameters(Sent in URL)JSON object, optional
Use this key to send data via URL i.e., the data will be sent as query parameters, when the webhook is triggered.
The URL parameters are applicable only for the GET HTTP method.
Possible parameters:
- module_parameters (mandatory) : Pull dynamic values from CRM fields. Example, ${!Leads.Email}
- custom_parameters : You can manually specify any static values. Example, "API_version": "v2"
- user_defined_parameters : You can define any predefined content or templated content. Example, "message": "Webhook for ${!Leads.Last_Name}"
date_time_formatJSON object, optional
Specify how the date and time format to be sent in the webhook. If you include Date or DateTime fields in the module parameters, you can choose the format in which these values will be sent to the external service.
- date_formatstring, optional
  Specify the format for date fields. Default format is dd-mmmm-yyyy.
- datetime_formatstring, optional
  Specify the format for date and time fields. Default format is dd-mm-yyyy H:M:S
- time_zonestring, optional
  Specify the time zone to use for date/time values. Default format is Etc/GMT+12.

Note

The "form_data" sends the module_parameters, custom_parameters, user_defined_parameters in the request body.
The "url_parameters" sends the module_parameters, custom_parameters, user_defined_parameters in the URL or query.

Sample input to configure a webhook without headers

Copied{
    "webhooks": [
        {
            "module": {
                "id": "5725767000000002175",
                "api_name": "Leads"
            },
            "name": "Webhook",
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "http_method": "POST",
            "description": "Description about the webhook",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Sample input to configure a webhook with headers

Copied{
    "webhooks": [
        {
            "headers": {
                "module_parameters": [
                    {
                        "name": "lead_email",
                        "value": "${!Leads.Email}"
                    },
                    {
                        "name": "lead_id",
                        "value": "${!Leads.Id}"
                    },
                    {
                        "name": "lead_owner",
                        "value": "${!Leads.Owner}"
                    }
                ],
                "custom_parameters": [
                    {
                        "name": "source",
                        "value": "website"
                    },
                    {
                        "name": "version",
                        "value": "1.0"
                    }
                ]
            },
            "module": {
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "description": "Protected Data",
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "http_method": "POST",
            "name": "Zoho's Data",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Sample input for "body" with "type" : "form_data"

Copied{
    "webhooks": [
        {
            "headers": {
                "module_parameters": [
                    {
                        "name": "lead_email",
                        "value": "${!Leads.Email}"
                    },
                    {
                        "name": "lead_id",
                        "value": "${!Leads.Id}"
                    },
                    {
                        "name": "lead_owner",
                        "value": "${!Leads.Owner}"
                    }
                ],
                "custom_parameters": [
                    {
                        "name": "source",
                        "value": "website"
                    },
                    {
                        "name": "version",
                        "value": "1.0"
                    }
                ]
            },
            "module": {
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "description": "Protected Data",
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "http_method": "POST",
            "name": "Zoho's Data",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Sample input for body with "type": "raw" and "format": "text"

Copied{
    "webhooks": [
        {
            "headers": {
                "module_parameters": [
                    {
                        "name": "lead_email",
                        "value": "${!Leads.Email}"
                    },
                    {
                        "name": "lead_id",
                        "value": "${!Leads.Id}"
                    },
                    {
                        "name": "lead_owner",
                        "value": "${!Leads.Owner}"
                    }
                ],
                "custom_parameters": [
                    {
                        "name": "source",
                        "value": "website"
                    },
                    {
                        "name": "version",
                        "value": "1.0"
                    }
                ]
            },
            "module": {
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "description": "Protected Data",
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "http_method": "POST",
            "name": "Zoho's Data",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Sample input for body with "type": "raw" and "format": "JSON"

Copied{
    "webhooks": [
        {
            "headers": {
                "module_parameters": [
                    {
                        "name": "lead_email",
                        "value": "${!Leads.Email}"
                    },
                    {
                        "name": "lead_id",
                        "value": "${!Leads.Id}"
                    },
                    {
                        "name": "lead_owner",
                        "value": "${!Leads.Owner}"
                    }
                ],
                "custom_parameters": [
                    {
                        "name": "source",
                        "value": "website"
                    },
                    {
                        "name": "version",
                        "value": "1.0"
                    }
                ]
            },
            "module": {
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "description": "Protected Data",
            "body": {
                "raw_data_content": "Zoho CRM Webhook API",
                "format": "Text",
                "type": "raw"
            },
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "feature_type": "workflow",
            "http_method": "POST",
            "name": "Zoho's Data",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Sample input for body with "type": "raw" and "format": "HTML"

Copied{
    "webhooks": [
        {
            "headers": {
                "module_parameters": [
                    {
                        "name": "lead_email",
                        "value": "${!Leads.Email}"
                    },
                    {
                        "name": "lead_id",
                        "value": "${!Leads.Id}"
                    },
                    {
                        "name": "lead_owner",
                        "value": "${!Leads.Owner}"
                    }
                ],
                "custom_parameters": [
                    {
                        "name": "source",
                        "value": "website"
                    },
                    {
                        "name": "version",
                        "value": "1.0"
                    }
                ]
            },
            "module": {
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "description": "Protected Data",
            "body": {
                "raw_data_content": "{\n  \"lead_id\": \"${!Leads.Id}\",\n  \"email\": \"${!Leads.Email}\",\n  \"owner\": \"${!Leads.Owner}\",\n  \"source\": \"website\",\n  \"version\": \"1.0\"\n}",
                "format": "JSON",
                "type": "raw"
            },
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "feature_type": "workflow",
            "http_method": "POST",
            "name": "Zoho's Data",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Sample input for body with "type": "raw" and "format": "XML"

Copied{
    "webhooks": [
        {
            "headers": {
                "module_parameters": [
                    {
                        "name": "lead_email",
                        "value": "${!Leads.Email}"
                    },
                    {
                        "name": "lead_id",
                        "value": "${!Leads.Id}"
                    },
                    {
                        "name": "lead_owner",
                        "value": "${!Leads.Owner}"
                    }
                ],
                "custom_parameters": [
                    {
                        "name": "source",
                        "value": "website"
                    },
                    {
                        "name": "version",
                        "value": "1.0"
                    }
                ]
            },
            "module": {
                "api_name": "Leads",
                "id": "5725767000000002175"
            },
            "description": "Protected Data",
            "body": {
                "raw_data_content": "{\n  \"lead_id\": \"${!Leads.Id}\",\n  \"email\": \"${!Leads.Email}\",\n  \"owner\": \"${!Leads.Owner}\",\n  \"source\": \"website\",\n  \"version\": \"1.0\"\n}",
                "format": "JSON",
                "type": "raw"
            },
            "url": "https://webhook.site/3588de27-e3bd-4237-894b-f140143f3d99",
            "feature_type": "workflow",
            "http_method": "POST",
            "name": "Zoho's Data",
            "authentication": {
                "type": "general"
            }
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
The ID given seems to be invalid
Resolution: Specify a valid field ID. Use the Get Fields metadata API to get the required IDs.
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory fields are missing
Resolution: Specify all mandatory fields in your input to configure the webhook. Refer to Input JSON section for to know the mandatory keys.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL.
Specify a valid request method. Refer to "Endpoints" section.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to configure webhooks. Create a new token with valid scope. Refer to Scope section for details.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to Request URL section for details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "webhooks": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "5725767000007093002"
            },
            "message": "webhook created successfully",
            "status": "success"
        }
    ]
}