Webhooks

Webhooks

Webhook 有助于从 Zoho Projects 自动向第三方应用程序发送 HTTP 通知。使用 Webhook，您可以配置自己的 HTTP URL，并将其与特定的业务规则关联，从而自动化与问题相关的整个通知流程。要了解更多关于 Webhook 的信息，请参阅 WebHooks.org。


Notes
可用性：最新用户型企业版

配置 Webhook

  1. 点击顶部导航面板中的 。

  2. 导航至“问题跟踪”>“Webhook”。

  3. 点击“添加 Webhook”。

  4. 在 Webhook 页面中，指定所有必要的参数。

  5. 点击“保存”。



Webhook 配置中的字段列表

 

字段名称

描述

数据类型

约束

 名称

指定 Webhook 名称。

文本

100个字符

通知 URL

指定第三方应用程序的 REST API URL。

URL

1000 个字符

方法

选择 API 方法类型 - POST 或 GET。默认情况下，选择 POST 方法。

单选按钮

 

附加问题参数

  • 附加参数有两种方式 - 使用标准格式或用户自定义格式（xml、json 等）。

  • 指定参数名称。并指定从问题字段中选择的相应参数值。

  • 这些参数对于触发向第三方的 webhook 至关重要。

文本

3000 个字符

附加自定义参数

  • 指定 webhook 的参数名称及其对应的值。

  • 此键值对主要用于发送 Auth 令牌、API 密钥等。

文本

3000 个字符

预览URL

预览完整的 webhook URL 以通知第三方应用程序。

只读

只读

 

将 Webhook 关联到业务规则

  1. 在“业务规则”中，导航至“规则详情”->“条件”->“操作”。

  2. 在“操作”中，点击“调用 Webhook”。

  3. 点击 为业务规则创建新的 Webhook，或点击 调用现有的 Webhook。


  1. 点击“保存规则”。


测试 Webhook 集成

  1. 根据您的业务规则标准，在 Zoho Projects 中添加测试数据。

  2. 在您的应用程序中，检查通过 Webhook 通知从 Zoho Projects 收到的更新/数据。

  3. 如果出现错误或数据不匹配，请修改 Zoho Projects 中的 Webhook 设置。

  4. 继续测试，直到 Zoho Projects 在您的应用程序中获得所需的结果。

‌‌
Notes
Webhooks 支持问题相关参数（问题标题、状态、受让人等）和自定义参数。

 

  • 每个 Webhook 仅允许 10 个问题相关参数和 5 个自定义参数。

  • 仅允许一个用户定义格式（xml、json 等）的问题相关参数。

  • 用户定义格式的问题相关参数示例：<issue-data><title>${Issue.IssueTitle} </title><key>${Issue.IssueKey} </key></issue-data>

  • Webhook 仅通过业务规则触发，即执行业务规则时，将调用关联的 Webhook。

  • 一个业务规则仅关联一个 Webhook，而多个业务规则可映射到同一个 Webhook。

  • 每天仅允许 1000 次 Webhook 调用。

  • 失败的 Webhook 执行不会重试。

  • 如果 Webhook 调用连续 10 次失败，Webhook 将被停用。

  • 如果达到当天的 Webhook 调用阈值，或 Webhook 因连续失败而被禁用，则不会发送邮件通知。

  • Webhook 失败会被审核，“Webhook 失败”页面仅显示最近 100 次失败。



错误代码


当 Webhook 执行失败时，Zoho Projects 中会显示以下错误消息之一：


HTTP 状态代码

  • 400 错误请求 - 通常缺少必需参数。

  • 401 未授权 - 没有有效的身份验证令牌。

  • 402 请求失败 - 参数有效但请求失败。

  • 404 未找到 - 请求的项目不存在。

  • 500、502、503、504 服务器错误 - 第三方应用程序出现问题。

  • 错误代码 1 - 暂时无法连接到 API 服务器。您需要检查 API 服务器日志和防火墙设置，以查看我们从 Zoho Projects 发送的请求。


自定义错误

  • 内部流程失败 - 由于处理 Webhook 时出现错误，导致 Webhook 无法执行。

  • 达到当日限额 - 公司达到当日最高限额。


业务场景

向项目所有者发送短信提醒。

目的

当问题在问题跟踪器中被标记为“Show Stopper”时，您可以通过将 Webhook 关联到业务规则，向项目所有者发送包含问题标题的短信。 

 

预定义的要求

  • 短信网关服务中的账户

  • 访问业务规则和 Webhook 的权限


步骤

  • 在短信网关服务中创建账户

  • 在 Zoho 问题跟踪器中配置 Webhook

  • 设置业务规则

  • 测试您的 Webhook 集成


步骤 1：在短信网关中创建账户

在您的短信网关服务中，创建一个账户并获取以下信息以配置 Webhook：

  • API URL

  • 用户名

  • 密码

  • API ID


目前，Zoho 已与以下短信网关提供商合作：

  1. Bulk SMS

  2. Clickatell

  3. Screen Magic

  4. Valueleaf

  5. Solutions Infini

您可以从上述供应商处购买短信积分和 API 详细信息。


步骤 2：配置 Webhook

在 Webhook 页面中，指定以下详细信息：

 

通知 URL：

 

http://<IP 地址>/smsgateway/post - POST 方法

用户自定义格式的参数：

参数名称 - 文本

参数值 -  Hi ${Issue.ProjectOwner},

                        Following Issue is marked as ${Issue.Severity}.

                        ${Issue.IssueKey} - ${Issue.IssueTitle}

                        Due on ${Issue.DueDate}

参数值 (名称 = 数字):

                       user = <gateway_user_name>

                       password = <api_password>

                       api_id = <gateway_unique_api_id>

                       to = <user_mobile_number>


Notes
在上述用户自定义参数中，我们使用了 Clickatell 网关进行演示。

 

步骤 3：设置业务规则

创建业务规则，具体规范如下：

 

  1. 业务规则名称 - Show Stopper

  2. 执行日期 - 字段更新 - 严重性

  3. 条件：严重性为 Showstopper 且状态未关闭

  4. 操作：

  • 可重现 - 始终

  • 分配至 - 开发人员

  • 调用 Webhook - 选择上一步创建的 Webhook

  1. 保存业务规则。了解更多关于创建业务规则的信息。


步骤 4：测试集成

在项目中添加一个测试问题并将其分配给开发人员。同时，将“严重性”的值更改为“Show Stopper”。这将触发与上述规则关联的 Webhook，项目所有者将收到一条包含问题标题、严重性以及截止日期的短信提醒。