Webhook

Webhook 是一个适合开发者的模块，方便了从 Zoho Projects 向第三方应用程序自动发送 HTTP 通知。使用 Webhook，您可配置自己的 HTTP URL 并将它们与特定业务规则关联，以便使与问题相关的整个通知过程实现自动化。如需了解有关 Webhook 的更多信息，请参阅 WebHooks.org

 配置 Webhook

  1. 导航至您的项目并点击问题。
  2. 从显示的选项中选择问题设置。
  3. 选择 Webhook。
  4. 点击右上角的添加 Webhook。
  5. 在 Webhook 页面中，指定所有必需的参数。
  6. 点击保存。

Webhook 配置中的字段列表 

字段名称描述数据类型约束
名称

指定 Webhook 名称。

文本

100 个字符

待通知的 URL

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

URL1000 个字符
方法

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

单选按钮-
附加问题参数
  • 按两种方式附加参数 - 使用标准格式或用户定义的格式（xml、json 等）。
  • 指定参数名称。然后指定从问题字段选择的相应参数值。
  • 在向第三方触发 webhook 时，这些参数很重要。
文本3000 个字符
附加自定义参数
  • 指定 webhook 的参数名称和相应值。
  • 此键/值对主要用于发送身份验证令牌、api 密钥等。
文本3000 个字符
预览 URL

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

只读只读

 将 Webhook 与业务规则关联

  1. 在业务规则中，导航至规则详情 -> 标准 -> 操作。
  2. 在操作中，点击调用 Webhook。
  3. 点击  以创建新 Webhook 或点击  以便为业务规则调用现有 Webhook。
  4. 点击保存规则。

了解更多有关配置业务规则的信息。

 测试 webhook 集成

  1. 根据您的业务规则标准在 Zoho Projects 中添加测试数据。
  2. 在您的应用程序中，通过 webhook 通知检查从 Zoho Projects 收到的更新/数据。
  3. 如果存在错误或数据不匹配，请在 Zoho Projects 中修改您的 webhook 设置。
  4. 继续测试，直至从 Zoho Projects 向您的应用程序传递期望的结果。

注：

  • Webhook 支持问题相关的参数（问题标题、状态、被分派人等）和自定义参数。

 已知的限制

  • 每个 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 服务器。您需要为我们从 Zoho Projects 发送的请求检查 API 服务器日志和防火墙设置。

自定义错误

  • 内部处理故障 - 当由于在处理 webhook 时出现错误而导致未执行 webhook 时。
  • 达到日限制 - 当公司达到一天的最大限制时。

 业务场景

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

用途

当问题在您的问题追踪中标记为中断性故障时，您可通过将 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：

  1. http://<IP Address>/smsgateway/post - POST 方法 

用户定义格式的参数：

参数名称 - 文本

参数值 -

${Issue.ProjectOwner} 你好，

以下问题已标记为 ${Issue.Severity}。

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

截止期为 ${Issue.DueDate}

自定义参数（名称 = 值）：

用户 = <gateway_user_name>

密码 = <api_password>

api_id = <gateway_unique_api_id>

发送至 = <user_mobile_number>

注：

  • 在上述用户定义和自定义参数中，出于演示目的，我们使用了 Clickatell 网关。
 

 第 3 步：设置业务规则

创建具有以下规格的业务规则：

  1. 业务规则名称 - 中断性故障 
  2. 执行条件 - 字段更新 - 严重性等级
  3. 标准：严重性等级为“中断性故障”，状态为“未关闭”
  4. 操作：
    • 是否可重现 - 总是
    • 分配给 - 开发者
    • 调用 Webhook - 选择上一步创建的 webhook
  5. 保存业务规则。了解更多有关创建业务规则的信息。

 第 4 步：测试您的集成

在项目中添加测试问题并将它分配给开发者。此外，将严重性等级的值更改为中断性故障。这将触发与上述规则关联的 webhook，且项目所有者将收到带有问题标题、严重性等级和到期日期的短信提醒。