About webhooks
- To start using a webhook, you need to link your application with the third party tool using a HTTP URL. This URL will receive data when a set of events are triggered. When the action related to any of the events are triggered, the data is sent to the URL.
- Triggers are set of events that you choose to send notifications when there is an update.
Availability: Premier, Enterprise and Zoho One planDefined set of webhook fields
Field Name | Purpose | Limitations | Mandatory fields |
Webhook Name | Enter your webhook name | 150 characters | This is a mandatory field |
Description | Enter a description for your webhook | 20000 characters |
|
URL |
1. Enter the REST API URL of your third party application.
2. It is the URL where the HTTP request is triggered when the events are executed.
| 200 characters | This is a mandatory field |
Module |
Webhooks are module specific in Zoho Sprints. You can create a webhook for each module.
|
| This is a mandatory field |
Trigger Events |
1. Each module has its respective trigger events.
2. Select the trigger events based on the module you choose.
3. The URL is triggered when the events are executed.
|
| This is a mandatory field |
Method | Choose the API method for your event.
- POST - PUT - DELETE - GET |
| This is a mandatory field |
Entity Parameters |
1. Parameters that are associated with a particular module (projectid, sprintid, etc.)
2. Append parameters either in the standard format (JSON, XML, etc. or name = value) or a user defined format.
| 25 parameters |
|
Custom Parameters |
1. These are general parameters that are not associated to a particular module.
2. Custom parameters are mainly used to send API keys, oAuth tokens, etc. that are used for triggering the webhook.
| 10 parameters |
|
Header Parameters |
You can also define header parameters in your HTTP request.
| 10 parameters |
|
URL Preview |
1. It is the preview of the webhook URL with all the appended parameters.
2. This URL is used to notify the third party application.
| Read-only mode |
|
Feature behavior
- Your webhook URL should always commence with http:// or https:// or www.
- You can create only 25 webhooks for each particular module.
- You can associate a webhook only for a particular module. Once associated, you cannot associate the webhook to a different module.
- You can view the details of your failed webhook calls and webhook logs only for the previous five days.
- Your URL will get suspended if the webhook fails for five consecutive attempts. You must reactivate it.
Error codes
HTTP Status Error Code | Reason |
400 Bad Request | Missing parameter |
401 Unauthorized | Invalid oAuth token |
402 Request Failed | Valid parameters but the request failed |
404 Not Found | Request item doesn't exist |
500, 502, 503, 504 Server Errors | There's a problem with the third party application |
Example
Requirements
- Account in Zoho Projects.
- Permission to access the API.
Steps to follow
- Enter values in the fields in the webhook creation form.
- Enter the webhook name. Here, we have named it as 'Milestone - Sprints'.
- In the URL, enter the third party application's URL. Here, Zoho Projects is the third party application.
- Your webhook URL should always commence with https:// or http:// or www.
- Enter a description for the webhook URL.
- The purpose of the webhook is when the user creates a sprint in Zoho Sprints it should be added as a milestone in Zoho Projects. Here, the action is using the 'Sprints' module.
- Select the module Sprint.
- Choose the trigger event as 'Sprint Added'. You can also choose the other actions like Sprint Update, Sprint Delete, Sprint Start, Sprint Complete.
- Select the method as POST.
4. Parameters in user defined format
