Zoho Workerly | Webhooks

Webhooks


Webhooks facilitates communication with third-party applications by sending instant web notifications every time an event occurs in Zoho Workerly. With Webhooks, you can configure HTTP URLs and associate them in workflow rules to automate the entire notification process. 

Ideal Users

  • Workerly Users with Manage Workflow permissions
  • Programmers with REST API skills
Availability

Profile Permission Required: Users with the Manage Workflow permissions in can access this feature.

List of Fields in Webhook

Field Name Description Data Type Maximum Limit
Name Specify name of the webhook. Text Alphanumeric(50)
Description Add a description for the webhook. Text 200 characters
URL to Notify Specify the REST API URL of the third-party application. URL 200 characters
Method Select type of API method - POST or GET. By default, system selects POST method. Radio Button -
Module

Choose one of the Zoho Workerly modules.

Supported Modules:

  • Workerly primary module, such as Temps, Jobs, Timesheets, Clients, Contacts, etc.
  • Events and Tasks

Note: You cannot set up webhooks for Call Logs and Notes modules.

Picklist -
Append Entity Parameters

Specify the Parameter Name and corresponding Parameter Value. This is the request parameters sent while triggering the webhook notification to third-party application.

Supported Modules:

  • Workerly primary modules
  • User
  • Organization
String 3000 characters
Append Custom Parameters Specify the Workerly 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 URL Preview the complete webhook URL to be notified to the third-party application. Text Read-only


Set Up Webhooks

Setting up Webhooks includes the following three steps:

  • Create a webhook.
  • Associate webhook to a workflow rule.
  • Test webhook integration.

To create a webhook
 

  1. Navigate to Setup > Automation > Workflow > Webhooks.
  2. In the Webhooks page, click Configure Webhook.
  3. In the New Webhook page, specify all necessary parameters.
  4. Click Save.

Recognize Unsupported Merge Field Values

Sometimes you may notice that the merge field values you have used in the Value Description editor of your webhook now get displayed as ${Unsupported_Field}. The following are some of the reasons why this happens.

Custom field deleted

The merge field whose value you have inserted has been deleted. If your webhook's Value Description editor continues to contain the merge field value of a deleted field, that value will be displayed as ${Unsupported_Field}.

Custom look-up field deleted

The custom look up field whose value you have inserted has been deleted. If your webhook's Value Description editor continues to contain the merge field value of a deleted look-up field, that value will be displayed as ${Unsupported_Field}.

Field not listed in the list of Available Merge Fields

If you have used the merge field value of a field that is not among the list of available merge fields for the selected module, then it will be displayed as ${Unsupported_Field}. For example, if you insert the merge field value ${Candidates.Candidate Id} in the Value Description editor for the Job Openings module, it will get displayed as an unsupported field.

To associate webhook to a workflow rule:

  1. Navigate to Setup > Automation > Workflow
  2. In the Workflow Rules page, click the Create Rule.
  3. In the Create New Rule page, specify workflow rule parameters.
  4. Under Workflow Actions, select webhooks.
  5. In the Call Webhook popup, select the required webhook and click Associate.
  6. Click Save.

To test the webhook integration:

  1. Add test data in Workerly according to your workflow rule criteria.
  2. In your application check for the data received from Zoho Workerly via webhook notification.
  3. If there is an error or data mismatch, modify your webhook settings in Zoho Workerly.
  4. Continue this test until you obtain the required data from Zoho Workerly to your Application.

Note

  • You can associate up to 6 (1 Instant Action and 5 Time-Based Actions) webhooks per workflow rule.
  • You can transfer data for a maximum of 10 Workerly fields from Zoho Workerly to third-party applications using webhook.
  • You cannot retrieve data from other Apps to Zoho Workerly using webhooks.
  • You must update the API ticket regularly according to limits in third-party applications.
  • You will not receive any email notification, if the Webhook integration stopped functioning due to any issue in a third-party API.
  • In webhooks, we allow maximum 10000 characters for user defined format, while using the POST method.
  • If there is any failure in the process, Webhook will send a notification first, Zoho Workerly system will send a second notification after 15 min. Thereafter, the system will not send any Webhook notifications for that particular workflow trigger.
  • If you exceed the maximum count per day, the system will not send remaining Webhook notifications to third-party applications and will notify the failure to Administrator.
  • In the URL to Notify field, if you want to specify a port number, please note that only 80 or 443 port numbers are supported.
  • Zoho Workerly gives an option to select the required Date/Date Time format and Time Zone during Webhook param configuration.
  • Limits for Webhooks:
  • Professional Edition - 10000 calls/day or 100 calls/user license (whichever is lower).
  • Enterprise Edition - 20000 calls/day or 500 calls/user license (whichever is lower).

 Business Scenario

A mass hire is happening and all temps are to be sent a SMS alert. The process can be simplified using webhooks.

Purpose

Notify temps through an SMS about the mass hire event.

Pre-requisite

  • Account in SMS gateway service
  • Permission to access Workflow Rules

Procedure

  1. Create an account in SMS gateway service 
  2. Configure webhook in Zoho Workerly 
  3. Set up Workflow Rule 
  4. Test your webhook integration 

Step 1: Create an account in SMS gateway service

In your SMS gateway service, create an account and get these details to configure webhook:

  • Workerlyer
  • Candidate Name
  • Opportunity Amount
  • Interview Details
  • Interview Scheduled Time

Currently Zoho has partnered with the following SMS Gateway providers:

  • Twilio
  • Clickatell 
  • Screen Magic 
  • Message Media

You can buy SMS credits and API details from the above vendors.

Step 2: Configure Webhook in Zoho Workerly

Select the following Fields from the Interviews module while setting up user-defined parameters:

  • Domain Name of SMS gateway
  • Username
  • Auth Token

In webhook, specify the following details:

URL to Notify:

  1. http://<Domain Name>/smsgateway/post - POST method
  2. User-defined Parameters (XML or JSON)
  3. <?xml version="1.0"?>
  4. <m:Library xmlns:m="http://www.screen-magic.com/" xmlns="http://www.defns.com/">
  5. <username>xxxx@xxxxx.com</username>
  6. <senderid>SMS-Provider</senderid>
  7. <accountid>XXXXXXX</accountid>
  8. <authtoken>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</authtoken>
  9. <message mobilenumber="${User.Mobile}">Hi ${Interviews.Interviewer}, An Interview has been scheduled for you on ${Interviews.From} at ${Interviews.Location} for candidate: ${Interviews.Candidate Name}</message>
  10. </m:Library>

Note

In the above XML string, we've used a Screen Magic gateway for demonstration purpose.

Step 3: Set up Workflow Rule

Follow these steps in the Workflow Rule page:

  1. Create a Workflow for all new interviews.
    • Type is New Business.
    • Stage is Closed Won.
    • Choose Closing date.
  2. Configure Webhook as mentioned above.
  3. Click Save and Associate
  4. Save workflow rule.

Step 4: Test your Webhook Integration

  1. Add a test interview record with all the updated Interview details.
  2. In your mobile phone check for the SMS alert. If you've not received SMS, modify the webhook configuration and continue testing. After successful testing, remove test entries and roll-out this integration to your Workerly users.

Refer Error Codes

When execution of webhook fails, one of the following error messages are displayed in Zoho Workerly:

 HTTP Status Codes

  • 400 Bad Request - Often missing a required parameter.
  • 401 Unauthorized - No valid Auth Token provided.
  • 402 Request Failed - Parameters were valid but request failed.
  • 404 Not Found - The requested item doesn't exist.
  • 500, 502, 503, 504 Server errors - Something went wrong on third-party application.
  • Error Code 1 - Temporarily not able to connect to the API server. You need to check API server logs, firewalls settings for our requests sent from Workerly.

 Custom Errors

  • Internal process failure - When the webhook is not executed due to errors in processing the webhook.
  • Day limit reached - When the company reached the maximum limit for the day.

    Access your files securely from anywhere

      Zoho CRM Training Programs

      Learn how to use the best tools for sales force automation and better customer engagement from Zoho's implementation specialists.

      Zoho CRM Training
        Redefine the way you work
        with Zoho Workplace

          Zoho DataPrep Personalized Demo

          If you'd like a personalized walk-through of our data preparation tool, please request a demo and we'll be happy to show you how to get the best out of Zoho DataPrep.

          Zoho CRM Training

            Create, share, and deliver

            beautiful slides from anywhere.

            Get Started Now


              Zoho Sign now offers specialized one-on-one training for both administrators and developers.

              BOOK A SESSION









                                            You are currently viewing the help pages of Qntrl’s earlier version. Click here to view our latest version—Qntrl 3.0's help articles.




                                                Manage your brands on social media

                                                  Zoho Desk Resources

                                                  • Desk Community Learning Series


                                                  • Digest


                                                  • Functions


                                                  • Meetups


                                                  • Kbase


                                                  • Resources


                                                  • Glossary


                                                  • Desk Marketplace


                                                  • MVP Corner


                                                  • Word of the Day


                                                    Zoho Marketing Automation

                                                      Zoho Sheet Resources

                                                       

                                                          Zoho Forms Resources


                                                            Secure your business
                                                            communication with Zoho Mail


                                                            Mail on the move with
                                                            Zoho Mail mobile application

                                                              Stay on top of your schedule
                                                              at all times


                                                              Carry your calendar with you
                                                              Anytime, anywhere




                                                                    Zoho Sign Resources

                                                                      Sign, Paperless!

                                                                      Sign and send business documents on the go!

                                                                      Get Started Now




                                                                              Zoho TeamInbox Resources



                                                                                      Zoho DataPrep Resources



                                                                                        Zoho DataPrep Demo

                                                                                        Get a personalized demo or POC

                                                                                        REGISTER NOW


                                                                                          Design. Discuss. Deliver.

                                                                                          Create visually engaging stories with Zoho Show.

                                                                                          Get Started Now









                                                                                                              • Related Articles

                                                                                                              • Workflow Rules

                                                                                                                Workflow Rules in Zoho Workerly, are a set of actions (alerts, tasks and field updates) that are executed when certain specified conditions are met. These rules automate the process of sending email alerts, SMS alerts, assigning tasks and updating ...
                                                                                                              • Managing Workflow

                                                                                                                Workflow management helps you to automate your staffing processes. You can automatically assign tasks to users, based on the criteria defined in the rules and update certain fields. Workflow automation consists of the following components: Workflow ...
                                                                                                              • Workerly Variables

                                                                                                                Workerly Variables are pseudo-module fields that are used to store static and reusable information in your Zoho Workerly account. A Workerly Variable can have unique set of values and can be widely used as merge fields in Email templates. It can also ...
                                                                                                              • Audit Logs

                                                                                                                The Audit Log is a chronological sequence of entries, each resulting from the actions performed by Users in Zoho Workerly. Audit logs are helpful to determine the happenings before and after an event and also to identify records associated with ...
                                                                                                              • Profile Permissions

                                                                                                                Profiles in Zoho Workerly help you define permissions for a set of users. For instance, the permissions required for a person from one Agent in the team might differ from the permissions required by another Agent. You can define the permissions for ...
                                                                                                                Wherever you are is as good as
                                                                                                                your workplace

                                                                                                                  Resources

                                                                                                                  Videos

                                                                                                                  Watch comprehensive videos on features and other important topics that will help you master Zoho CRM.



                                                                                                                  eBooks

                                                                                                                  Download free eBooks and access a range of topics to get deeper insight on successfully using Zoho CRM.



                                                                                                                  Webinars

                                                                                                                  Sign up for our webinars and learn the Zoho CRM basics, from customization to sales force automation and more.



                                                                                                                  CRM Tips

                                                                                                                  Make the most of Zoho CRM with these useful tips.



                                                                                                                    Zoho Show Resources