Enable Notifications

Purpose

To enable instant notifications of actions performed on a module.

Endpoints

POST /actions/watch

Request Details

Request URL

{api-domain}/crm/{version}/actions/watch

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.notifications.{operation_type}

Possible operation types

ALL - Full access to notification data
WRITE - Edit instant notification details
CREATE - Enable instant notifications

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v3/actions/watch"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@inputData.json"

Input JSON Keys

tokenString, optional
To ensure that the notification is sent from Zoho CRM, by sending back the given value in notification URL body. By using this value, user can validate the notifications. Maximum length of characters is 50.
Possible values: Example: TOKEN_FOR_VERIFICATION_OF_1000000068001
notify_urlString, mandatory
URL to be notified (POST request). Whenever any action gets triggered, the notification will be sent through this notify url.
Possible values: String values. Example: https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2
channel_idlong, mandatory
The given value is sent back in notification URL body to make sure that the notification is for a particular channel.
Possible values: Channel ID. Example: 1000000068001
return_affected_field_valuesboolean, optional
It returns the affected fields with their values and corresponding record IDs if return_affected_field_values in the input is true. If false, the return_affected_field_values key will not be shown in the response.
channel_expiryString (ISO Date time), optional
To set the expiry time for instant notifications. Maximum of only one day from the time they were enabled. If it is not specified or set for more than a day, the default expiry time is for one hour.
Possible values: ISO Date time. Example: 2018-02-02T10:30:00+05:30
eventsJSONArray["{module_api_name}.{operation}", "{module_api_name}.{operation}"], mandatory
To subscribe based on particular operations on selected modules.
Possible values: JSON Array of the provided format. Example: ["Leads.create","Sales_Orders.edit","Contacts.delete"]. Possible operation types - create, delete, edit, all
notify_on_related_actionboolean, optional
To enable notification when there is any action on any associated records. The default value is FALSE.

To get notification on a URL

On trigger of any notification-enabled event in a module, Zoho CRM sends a notification to the user through the notify URL.

Sample Input

Copied{
    "watch": [
        {
            "channel_id": "1000000068001",
            "events": [
                "Solutions.create",
                "Price_Books.create",
                "Contacts.create",
                "Solutions.edit"
            ],
            "channel_expiry": "2018-02-02T10:30:00+05:30",
            "token": "TOKEN_FOR_VERIFICATION_OF_1000000068001",
            "return_affected_field_values": true,
            "notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2"
        },
        {
            "channel_id": "1000000068002",
            "events": [
                "Deals.edit"
            ],
            "channel_expiry": "2018-02-02T10:30:00+05:30",
            "token": "TOKEN_FOR_VERIFICATION_OF_1000000068002",
            "return_affected_field_values": true,
            "notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1&key2=val2&key3=val1"
        },
        {
            "channel_id": "1000000068003",
            "events": [
                "Cases.all"
            ],
            "channel_expiry": "2018-02-02T10:30:00+05:30",
            "token": "TOKEN_FOR_VERIFICATION_OF_1000000068003",
            "return_affected_field_values": true,
            "notify_url": "https://www.zoho.com/callback?authorization=Zoho-oauthtoken 1000.23dnsbbbh455jnn&key1=val1"
        }
    ]
}

Possible Errors

MANDATORY_NOT_FOUND HTTP 400
One of the mandatory fields (events, channel_id, notify_url) is not found. Refer to the "details" key in the response to know which mandatory field is missing.
Resolution:Ensure that all the mandatory fields are given in the input.
INVALID_DATA HTTP 400
The length of the token is greater than 50 characters.
Resolution: Ensure that the token passed is less than 50 characters in length.
INVALID_DATA HTTP 400
The user do not have permission to subscribe to the module.
Resolution: Contact your system administrator

Sample Response

Copied{
    "watch": [
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2018-02-02T10:30:00+05:30",
                        "resource_uri": "https://www.zohoapis.com/crm/v3/Solutions",
                        "resource_id": "1000000000091",
                        "resource_name": "Solutions",
                        "channel_id": "1000000068001"
                    },
                    {
                        "channel_expiry": "2018-02-02T10:30:00+05:30",
                        "resource_uri": "https://www.zohoapis.com/crm/v3/Contacts",
                        "resource_id": "1000000000045",
                        "resource_name": "Contacts",
                        "channel_id": "1000000068001"
                    },
                    {
                        "channel_expiry": "2018-02-02T10:30:00+05:30",
                        "resource_uri": "https://www.zohoapis.com/crm/v3/Price_Books",
                        "resource_id": "1000000000097",
                        "resource_name": "Price_Books",
                        "channel_id": "1000000068001"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2018-02-02T10:30:00+05:30",
                        "resource_uri": "https://www.zohoapis.com/crm/v3/Deals",
                        "resource_id": "1000000000047",
                        "resource_name": "Deals",
                        "channel_id": "1000000068002"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2018-02-02T10:30:00+05:30",
                        "resource_uri": "https://www.zohoapis.com/crm/v3/Cases",
                        "resource_id": "1000000000089",
                        "resource_name": "Cases",
                        "channel_id": "1000000068003"
                    }
                ]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
        }
    ]
}

Response JSON Keys

serverinteger
Represents the server time when the notification was sent to the notify URL.
affected_valuesJSON array
It returns the affected fields with their values and corresponding record IDs if return_affected_field_values in the input is true and the value is false, return_affected_field_values JSON array will not be shown in the response.
query_paramsJSON object
Represents the parameters if any were specified in the notification request.
resource_uriJSON object
Represents the URI of the module you have specified to receive notifications when certain actions are performed in the module.
idsJSON array
Represents the unique IDs of the affected records.
affected_fieldsJSON array
Returns the modified fields (affected fields) in a specific record. Note the subforms, participants, and product_details fields will be ignored in the response.
operationstring
Represents the operation performed on the module.
modulestring
Represents the module you have subscribed from which you want to be notified of any changes.
channel_idlong
Represents the subscribed channel ID.
tokenstring
Represents the value received in the callback to ensure that the notification is from Zoho CRM.

Sample response received via notify URL for a record update in a module

Copied{
  "server_time": 1719309544639,
  "affected_values": [
    {
      "record_id": "5725767000003093005",
      "values": {
        "Probability": 75,
        "Stage": "Proposal/Price Quote"
      }
    }
  ],
  "query_params": {
    "key1": "val1",
    "key2": "val2",
    "?authorization": "Zoho-oauthtoken 1000.23dnsbbbh455jnn"
  },
  "module": "Deals",
  "resource_uri": "https://www.zohoapis.com/crm/v2/Deals",
  "ids": [
    "5725767000003093005"
  ],
  "affected_fields": [
    {
      "5725767000003093005": [
        "Stage",
        "Probability"
      ]
    }
  ],
  "operation": "update",
  "channel_id": "1000000068002",
  "token": "TOKEN_FOR_VERIFICATION_OF_1000000068001"
}