Configuring Webhooks

Webhooks feature in the application uses a mechanism to send real-time data to another third party system or URL when it is executed. These webhooks push data to a specific URL as soon as an event happens, and thereby help the users to invoke any action in the third party application instantly.

For example, consider the scenario in an IoT setup where you have set up the Fuel Monitoring solution for a diesel generator. Here, you can create a webhook action in an alarm rule to push the low fuel reading to a third-party application to initiate a purchase order.

Webhook Parameters

Lets understand the Webhook parameters before proceeding with the creation of the webhook. These parameter values are required when providing the details in the Webhook Creation form.

Field Name	Description
Name	The unique name of the webhook.
Description	A short description about the webhook.
Method	The type of the API method - POST or GET. Choosing POST allows you to enter the values in the fields of the associated application, whereas GET allows you to retrieve information to update in the fields of a record in Zoho IoT. Note: By default, the system will select the POST method.
URL to Notify	The REST API URL of the third-party application.
Connection	The desired Authorization type: General( includes API Key or AUTH Token) and Connection(OAuth, API Key, etc.).
Authentication Type	The connection for the webhook. Note: The connection option will only list the existing active connections. Either choose an existing connection or add a new one.
Header	The information section in a webhook URL is typically classified as Header and Body. Parameters added to the header section will have data that will synchronize with the header of other applications. In addition to the trigger information, header can customarily carry API Keys/Auth tokens. To form the Header URL parameters, choose the module parameters and/or custom parameters.
Module Parameters	The name, type, and corresponding value. Multiple parameters are added to build the string. This format is dynamic, and the IoT application gives you the options to choose the field values from the picklist. Parameter Types are: Zoho IOT Modules, Datapoints, and Alarms.
Custom Parameters	The name and corresponding value. The value in custom parameter is static, this key/value pair is mainly used to send the auth tokens, security tokens, API key, and so on.
User Defined Parameter	The parameter name and the parameter value. This format is also dynamic, with the ability to choose the type of value by including the variable as a placeholder using #.
Body	The body part of the URL containing information in the URL string about the trigger to other applications. You can choose to use None, Form-Data, or Raw Data from the picklist to configure the body part of the URL. Form-Data: Allows you to build the body part of the URL by simply appending together, parameter name, and parameter type, or parameter value. You can build Form-Data in three ways: using module parameters, custom parameters, and user-defined parameters. Raw Data: Apart from forming the parameters, you can also write your own data values in the text editor if you select the option Raw Data as body type. You can input data in either of the following formats Text or JSON. You can also use the # merge field feature to denote a field value within the script.
Preview URL	The preview URL displays the complete webhook URL for the GET and DELETE request method, while for the POST and PUT method, only the configured URL is displayed. To preview the URL, Click the Refresh icon in the bottom of the text editor. You can also copy the URL.

Creating Webhooks

To create a webhook action:

1. Access the Developer Application.
2. Select the Automate tab in the top, and select Actions in the left pane.
3. Click the Webhook tab. The available configurations will be displayed.

4. Select the category. Possible categories include alarm rules, workflow, and notification profile.
Note: The selected category determines the feature in which the webhook appears in the list of Actions i.e. in Alarm Rules, Workflows, or Notification Profiles.

For example, if a webhook named Asset Malfunction is created with Alarm Rules category selected, the webhook will be listed in the Actions > Webhooks when configuring an Alarm Rule. This will not be listed in Workflow or Notification Profiles creation forms.

5. Select the model/module and provide a name.

6. Provide the third-party URL to notify.

The third-party webhook URL is simply the endpoint of the external system you want to notify or retrieve data from.
For example, https://erp.exampxx.com/api/v1/purchase-orders/create or https://api.exampxx.com/refreshStatus

7. Select the method POST or GET action.

Here, POST is used to send, create, or notify third party, whereas, GET is used to retrieve information.
For example, for creating a new resource (purchase order) using a third party URL, the POST action in REST APIs is used.

POST https://erp.exampxx.com/api/v1/purchase-orders/create
GET https://api.exampxx.com/refreshStatus

8. Provide the description of the webhook action.

9. Select the preferred Authentication Type: General or Connections.
General: Provide the name and value for the parameters.
Connections: Select the connection from the available connections drop-down list. Refer to the Configuring Connections document for more details on creating a connection.

What is the advantage of using Connections in Webhooks?

When you configure a Webhook action directly, you have to enter the details like the API URL, authentication token, and headers every single time. This can be time-consuming and risky as credentials may get exposed in multiple places. With Connections, you need to configure the service and its authentication once, and then assign it to a Webhook action during creation. This makes it easier, as it is reusable across your Zoho IoT setup.

Example use case:
Suppose you want to send energy consumption alerts from Zoho IoT to Zoho CRM. Instead of manually adding authentication details in each Webhook, you just create one Connection for Zoho CRM. Then, whenever you create a Webhook action, you simply select the Notification Type as Connection and choose the relevant connection, no need to re-enter authentication values.

10. Provide the header and body for the webhook action.

11. Enter the body for the webhook action.

12. Click Save.

Availability

All Webhook actions require necessary permissions. Refer to Users and Profiles document for more details.

Check Feature Availability and Limits

Executing the Webhook Action

The webhook action will be triggered whenever the fuel level reaches a low and the alarm rule conditions or the notification profiles conditions are met.

The execution of the webhook can be verified in the audit logs:

Possible Webhook Execution Errors

Webhook execution may sometimes fail due to one of the following reasons:

Bad Request: A required parameter may be missing
Unauthorized Request: An invalid Auth Token is provided
Request Failed: Parameters were valid but request failed
Page not Found: The requested item doesn't exist
Third-party error: There is glitch in the third-party application
Third-party server not available: Disconnection at the third-party API server
Internal process failure: Error occurred when processing the webhook
Day limit reached: The org had reached the maximum limit for the day
Invalid URL: The URL is not accessible or has any restriction. It can be opened in another browser to check if accessible.
Socket timeout: If the webhook is invoked but response is not received until 10 seconds