Webhooks

Purpose

Webhooks communicate with third party applications by sending instant notifications every time when a user performs an action in the Zoho People organizational account data.

Webhooks are user-defined HTTP callbacks. In other words, it is a simple event notification via HTTP post. It will notify a URL by posting a message when certain events happen.

Benefits of Webhooks

  • Flexible and customizable.
  • Sends instant notifications to third party applications.
  • Users can integrate with their own custom applications or any third party applications.
  • Real-time data synchronization.
  • A complete webhooks list, webhook failures, and successes are provided.

Types of Webhooks

  • Webhooks List: Using Zoho People webhooks, you can communicate with the third party applications by sending instant notifications every time when a user performs an action on the organizational account data.
  • Failure Webhooks: The failure webhooks are listed on this page along with the details such as webhook name, form name, associated record, latest invoke time, redo an action and the response message. You can also filter the webhooks using the following options such as forms, the name of the webhooks and the duration period.
  • Successful Webhooks: The successful webhooks are listed on this page along with the details such as webhook name, form name, associated record, latest invoke time and the response message. You can also able to filter the webhooks using the following options such as forms, the name of the webhook and the duration period.

API

Zoho People provides APIs (Application Programming Interface) for integrating HR modules with third-party applications. With Zoho People API, you can extract employees data and form data in XML or JSON format and develop new applications or integrate with your existing business applications. As Zoho People API is independent of programming languages, you can develop applications in any programming language (Java, .Net, C, C++, PHP, etc.) .

To learn more, click here.

Fields in Webhooks

Field NameDescriptionData TypeMaximum Limit
NameSpecify name of the webhookTextAlphanumeric(50)
DescriptionAdd a description for the webhookText250 characters
URL to NotifySpecify the API URL of the third-party application or Zoho application (eg: Zoho People, Zoho Creator)URL250 characters
MethodSelect type of API method - POST or GET. POST is the default selected methodRadio Button-
ModuleChoose the 'Form' from which the data is to be communicated to the third-party applicationPicklist-
Append Entity ParametersSpecify the Parameter Name and corresponding Parameter Value. This is the request parameters sent while triggering the webhook notification to third-party application.String3000 characters
Append Custom ParametersSpecify the Zoho People Parameter Name and corresponding Value for the webhook. This is also the request parameters sent while triggering the webhook. The name and the value are as configured. This key/value pair is mainly used to send the Auth tokens, security tokens, etc.String-
Preview URLPreview the complete webhook URL to be notified to the third-party application.TextRead-only
 

Webhook configuration

Webhook is simple and easy to configure. You just need to configure HTTP URLs and associate them with a workflow rule to automate the workflow process. Please follow the steps below to configure webhooks:

  1. Log in as an Administrator.
  2. Go to Setup at the top of the page.
  3. Click Webhooks under Automation > Actions.
  4. Click + Add Webhook.
  5. Name the webhook.
  6. Add a description.
  7. Specify the third party URL to notify.
  8. Select API method type: POST or GET.
  9. Select the form name or the module from the list.
  10. Specify the parameter name and the corresponding parameter value. You can add only 10 entity fields as parameters specify the parameter in user defined format. Eg: XML, JSON etc., specify the custom parameter name and parameter value. You can add only 5 custom parameters

     11. Click Save

Example Scenario

Change Employee Status in Exit Form via Webhook

Let's consider a scenario - An employee is resigning his job and you want to change the status as Resigned in the Employee form. Before Webhook was introduced, you need to manually update changes twice in the Employee form as well as in the Exit form. But now, you can automatically POST notification in the Exit form by configuring Webhook using API. Please follow the steps below to configure webhook for this scenario.

  1. Log in as Administrator
  2. Go to Setup at the top of the page
  3. Click Webhooks under Automation
  4. Click New Webhook
  5. Name the Webhook
  6. Add a description
  7. Specify the URL to notify

https://people.zoho.com/people/api/forms/P_Separation/insertRecord

       8. Select API method type: POST

       9. Select the form name Employee from the list

      10. For the User Defined format, specify the Parameter Name xmlData and the Value Description as shown below:

  • <Request>
  • <Record>
  • <field name="Employee_ID">${ZOHO_LINK_ID}</field>
  • <field name="Interviewer">${Reporting_To}</field>
  • <field name="Separation_date">${Exit_Date}</field>
  • </Record>
  • </Request>

      11. Specify Custom Parameters: authtoken in the Parameter Name and the authtoken key in Parameter Value.

      12. Click Save

Note:

In the above XML string, the tag field represents the fields in Zoho People, the name represents the label name of the field and the value tag represents data to be pushed.

Custom Parameters

https://people.zoho.com/people/api/forms//insertRecord ?authtoken=XXXXXXXXXXXX&xmlData=

Note:

To use the API, you will require Zoho People authentication token from your Zoho People account. To generate Authtoken, click here.