Enable notifications

Enable instant notifications to receive alerts when specific actions are performed within Bigin modules. This API allows you to enable multiple notifications by creating unique channels, each functioning as an independent source.

Endpoints

POST /actions/watch

Request URL

{api-domain}/bigin/v2/actions/watch

Choose a domain-specific URL to replace {api-domain}

You can use a domain-specific URL to access Bigin resources. Based on the data center in which the Bigin account's resources are available, replace {api-domain} in the preceding request with one of the following API domain URLs:

For US: https://www.zohoapis.com
For EU: https://www.zohoapis.eu
For AU: https://www.zohoapis.com.au
For IN: https://www.zohoapis.in
For CN: https://www.zohoapis.com.cn
For JP: https://www.zohoapis.jp

For more information, read Multi DC Support.

Authorization

For this endpoint, pass the access token as an authorization header. Read OAuth Authentication for more information about access tokens.

Authorization: Zoho-oauthtoken <ACCESS_TOKEN>

You must authenticate using an access token that's associated with the following scope:

ZohoBigin.notifications.ALL
ZohoBigin.notifications.WRITE
ZohoBigin.notifications.CREATE

Sample request

Copiedcurl "https://www.zohoapis.com/bigin/v2/actions/watch" \
-X POST \
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf" \
-d "@notif-webhook.json"

Request parameters

The available request parameters are provided below:

Body parameters

token stringOptional

This value is sent back in the notification URL body to ensure that the notification is sent from Bigin. Users can use this value for validation, which is limited to a maximum length of 50 characters.

For example:

"token": "TOKEN_FOR_VERIFICATION_OF_1002"

notify_url stringRequired

A valid URL serves as a webhook to receive event notifications from Bigin. When a specific action is triggered, the notification is sent to this URL.

For example:

"notify_url": "https://www.example.com/callback/"

channel_id stringRequired

This is a unique identifier for a channel. You can create up to 100 channels, each with its own distinct channel ID in a single API call. To ensure that a notification originates from a specific channel, the channel ID is sent back in the notification when an action associated with that channel is triggered.

For example:

"channel_id": "1000000810"

channel_expiry stringOptional

This is the expiry time of the channel in ISO8601 format. After this time, notifications for the channel will no longer be sent. You can set the expiry time up to one day from the moment notifications are enabled for the channel. If you do not specify this value or set an expiry time beyond one day, the system will use the default expiration time of one hour.

For example:

"channel_expiry": "2023-11-02T10:30:00+05:30"

events jsonarrayRequired

This is a JSON array containing the module API name and operation type (e.g., Contacts.create, Pipelines.edit, and so on) for receiving notifications for specific actions within Bigin. This parameter allows you to customize notifications by specifying the module API name and operation type for record actions.

For example:

"events": ["Contacts.create","Accounts.edit","Pipelines.delete","Products.all"]

Sample request body

Copied{
    "watch": [
        {
            "channel_id": "1001",
            "events": [
				"Contacts.create"
			],
            "channel_expiry": "2023-10-02T10:30:00+05:30",
            "token": "TOKEN_FOR_VERIFICATION_OF_1001",
            "notify_url": "https://webhook.site/09fff50d-b355-42a9-9c2b-9e2147b2a5e5"
		},
        {
            "channel_id": "1002",
            "events": [
				"Pipelines.create"
			],
            "channel_expiry": "2023-11-02T10:30:00+05:30",
            "token": "TOKEN_FOR_VERIFICATION_OF_1002",
            "notify_url": "https://webhook.site/09fff50d-b355-42a9-9c2b-9e2147b2a5e5"
		}
	]
}

Response object

The response object contains the following details:

resource_uri string

The request url to access the module.

resource_id string

The unique identification of the module obtained from the value of resource_uri.

resource_name string

The API name of the module for which the notification has been enabled.

Possible error codes

The response of this resource includes HTTP status and error codes.

The most common HTTP error codes that occur when you request access to this endpoint are given in the following:

MANDATORY_NOT_FOUND HTTP 202
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 202
The length of the token is greater than 50 characters.
Resolution: Ensure that the token passed is less than 50 characters in length.

Sample response

Copied{
    "watch": [
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2023-09-14T20:46:13+05:30",
                        "resource_uri": "https://www.zohoapis.com/bigin/v2/Contacts",
                        "resource_id": "5436046000000002179",
                        "resource_name": "Contacts",
                        "channel_id": "1001"
				}
				]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
		},
        {
            "code": "SUCCESS",
            "details": {
                "events": [
                    {
                        "channel_expiry": "2023-09-14T20:46:13+05:30",
                        "resource_uri": "https://www.zohoapis.com/bigin/v2/Pipelines",
                        "resource_id": "5436046000000002181",
                        "resource_name": "Pipelines",
                        "channel_id": "1002"
				}
			]
            },
            "message": "Successfully subscribed for actions-watch of the given module",
            "status": "success"
		}
	]
}

Request body of the notification that Bigin sends to the notify URL

Copied{
    "server_time": 1696942911242,
    "query_params": {},
    "module": "Contacts",
    "resource_uri": "https://www.zohoapis.com/bigin/v2/Contacts",
    "ids": [
		"5436046000000930004"
	],
    "affected_fields": [],
    "operation": "insert",
    "channel_id": "1001",
    "token": "TOKEN_FOR_VERIFICATION_OF_1001"
}