使用 Webhook 监控事件

前提条件

• 确保 Yeastar P 系列 IPPBX 固件为 37.20.0.21 或更高版本。

• 你已启用 Yeastar P 系列 IPPBX API。
  注： 如果要监控分机状态或中继状态，需确保 高级设置 中的对应监控设置已启用。

  

• 你已从第三方应用程序获取有效的 Webhook URL。

  在本文的示例中，将使用由 Webhook.site 生成的 URL。

  

操作步骤

1. 登录 PBX 管理网页，进入 应用对接 > 二次开发接口。
2. 勾选 Webhook事件推送。

   

3. 添加一条 Webhook 并填写相关信息。

   本文示例中添加了一条 Webhook，当分机信息更新时，通过 POST 请求将事件通知推送到指定 URL。

   注： 最多支持添加 5 条 Webhook。
   
   • Webhook URL：输入 Webhook URL，该地址作为事件推送的目标地址。
   • Secret：系统自动生成的 32 个字符的密钥，用于对 Webhook 消息进行签名。发送 Webhook 事件时，系统会将生成的签名写入 X-Signature 请求头，可用于验证消息的真实性和完整性。
     提示：

     • 接收者收到 Webhook 请求后，可使用该密钥对收到的原始消息体执行 HMAC-SHA256 计算，并进行 Base64 编码，再将结果与 X-Signature 请求头中的签名进行比对。若两者一致，则表明消息正确且完整。
     • 如果密钥存在泄露风险，可点击 更新密钥。
   • 请求方式：根据第三方 Webhook URL 的要求，选择 GET 或 POST HTTP 请求方式。
   • 事件：选择要监控的事件。
     注：

     • 若要监控所有 PBX 事件，选择 所有。
     • 更多 API 事件相关信息，请参见 事件报告。
4. 要验证 Webhook 配置是否有效，点击 操作 栏中的 发送测试消息。

   如果测试成功，URL 指向的第三方应用将收到以下 JSON 格式的消息：

   { 
       "event": "test",
       "message": "This is a webhook connectivity test." 
   }

   本文示例中，Webhook.site 接收并展示了以下消息。

   

5. 在 超时时长（秒）字段中，设置等待第三方应用的 HTTP 响应的最长时间，时间范围为 3 - 10 秒。

   如果第三方应用未在指定时间内返回表示成功的 HTTP 响应 (2xx)，PBX 将根据 重试次数 的设置进行重试。

6. 在 重试次数 下拉选项中，选择在推送失败或未收到成功响应时，PBX 可重新发送请求的次数。
7. 点击 保存。

结果

当订阅的事件发生时，系统会自动发送事件报告。

本文示例中，当分机 1020 的显示号码被更新时，系统自动发送对应事件报告发送到指定 Webhook URL。