Webhooks facilitates communication with third-party applications by sending instant web notifications every time an event occurs in Zoho Recruit. With Webhooks, you can configure HTTP URLs and associate them in workflow rules to automate the entire notification process.
Scenarios
- You can add subscribers to the mailing list in Email Marketing software (e. g. MailChimp) based on candidates or contacts collected from your Website using Zoho Recruit's Web forms.
- You can trigger SMS reminders to Interviewers or Candidates, notifying them about events.
Ideal Users
- Recruit 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 Recruit modules.
Supported Modules:
- Recruit primary module, such as candidates, contacts, job openings, 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: - Recruit primary modules
- User
- Organization
| String | 3000 characters |
Append Custom Parameters | Specify the Recruit 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:
- Go to Setup > Automation > Actions > Webhooks.
- In the Webhooks page, click Configure Webhook.
- In the New Webhook page, specify all necessary parameters.
- 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:
- Go to Setup > Automation > Actions > Workflow rule
- In the Workflow Rules page, click the Create Rule.
- In the Create New Rule page, specify workflow rule parameters.
- Under Workflow Actions, select webhooks.
- In the Call Webhook popup, select the required webhook and click Associate.
- Click Save.
To test the webhook integration:
- Add test data in Recruit according to your workflow rule criteria.
- In your application check for the data received from Zoho Recruit via webhook notification.
- If there is an error or data mismatch, modify your webhook settings in Zoho Recruit.
- Continue this test until you obtain the required data from Zoho Recruit to your Application.
Important Notes
- 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 Recruit fields from Zoho Recruit to third-party applications using webhook.
- You cannot retrieve data from other Apps to Zoho Recruit 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 an issue in a third-party API.
- In webhooks, we allow maximum 10000 characters for a user-defined format, while using the POST method.
- If there is any failure in the process, Webhook will send a notification first, Zoho Recruit 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 Recruit 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 interviewers are to be sent an SMS alert. The process can be simplified using webhooks.
Purpose
Notify Interviewers through an SMS about the interviews that have been scheduled.
Pre-requisite
- Account in SMS gateway service
- Permission to access Workflow Rules
Procedure
- Create an account in SMS gateway service
- Configure webhook in Zoho Recruit
- Set up Workflow Rule
- Test your webhook integration
Step 1: Create an account in the SMS gateway service
In your SMS gateway service, create an account and get these details to configure webhook:
- Recruiter
- 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 Recruit
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:
http://<Domain Name>/smsgateway/post - POST method
User-defined Parameters (XML or JSON)
<?xml version="1.0"?>
<m:Library xmlns:m="http://www.screen-magic.com/" xmlns="http://www.defns.com/">
<username>xxxx@xxxxx.com</username>
<senderid>SMS-Provider</senderid>
<accountid>XXXXXXX</accountid>
<authtoken>XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX</authtoken>
<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>
</m:Library>
Note
In the above XML string, we've used Screen Magic gateway for demonstration purpose.
Step 3: Set up Workflow Rule
Follow these steps in the Workflow Rule page:
Create a Workflow for all new interviews.
- Type is New Interview.
- Stage is Closed.
- Choose Closing date.
- Configure Webhook as mentioned above.
- Click Save and Associate
- Save workflow rule.
Step 4: Test your Webhook Integration
Add a test Interview record with all the updated Interview details.
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 Recruit users.
Refer Error Codes
When execution of webhook fails, one of the following error messages are displayed in Zoho Recruit:
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 Recruit.
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.