Webhook

如何在 VergeOS 中配置 Webhook，以便向外部系统发送推送式消息，包括 Webhook 创建、任务负载设置和事件触发配置。

当特定事件发生时，Webhook 可实现向外部系统推送消息。触发事件发生后，Webhook 会向预定义的 URL 发送一个 HTTP 请求（通常是 POST）。对于通知和工作流自动化而言，这种推送机制比轮询更高效，因为接收系统无需定期检查更新。

Webhook 使用示例

VergeOS Webhook 允许对面向第三方系统的事件驱动通信进行高度配置，提供广泛的简化机会。以下基本示例演示了使用 Webhook 进行告警和工作流自动化的可能方式：

• 当同步任务产生错误时，向管理员频道发送 Slack 通知
• 当 VergeOS 租户上线时，向会计系统发送消息，以触发自动计费
• 当某个特定 VM 开机时，触发一个 Zapier 工作流，从而启动跨应用操作（例如报告、电子邮件、通知等）

配置步骤

要让 Webhook 生效，请按照以下步骤操作：

• 创建 Webhook：定义目标 URL、身份验证方法，以及外部系统所需的任何自定义标头
• 创建任务：定义要传递的载荷
• 创建事件：指定将激活该任务的某个发生情况

模块化设计

该 VergeOS 任务引擎 可灵活编排 Webhook、任务和事件。您可以为单个 Webhook 分配多个任务或事件，而单个任务也可以由多个不同事件触发。这种可组合的架构支持可扩展、可复用、并可根据您系统需求量身定制的工作流。

创建 Webhook

1. 导航到 系统 > 任务仪表板.
2. 点击 新建 Webhook 在左侧菜单中。
3. 配置 Webhook：

• 名称：为该 Webhook 提供一个描述性名称。
• URL：输入目标系统对外提供、用于接受 HTTP POST 请求的 API 端点。

通常，您需要在目标系统上为您的 VergeOS 系统显式授予对此端点的访问权限

授权类型

• Bearer 令牌 - 只输入 bearer token 字符串。（不要包含“Bearer”一词）
• API 密钥 - 只输入原始 API 密钥字符串。（不要包含任何前缀或关键词）
• Basic - 在提供的输入字段中输入用户名和密码。
• 无

标头

默认情况下，会包含一个标头用于指定载荷 content-type: application/json。此标头可根据需要移除或编辑，并可按需配置其他标头，以适配目标系统（例如更改内容类型、事件路由、速率限制、优先级等）- 若要更改自定义标头的顺序：勾选所需标头的复选框并使用上/下箭头按钮 - 使用加号按钮添加更多标头 - 铅笔按钮可在标头键/值对输入与手动输入完整标头语法之间切换

• 允许不安全证书：此选项用于在测试/开发环境中兼容自签名证书。 在生产系统和数据中使用不安全证书（尤其是公共 URL）存在风险，不建议这样做。
• 超时：定义等待目标系统响应的最长秒数（必须为 3 或更大）
• 重试：当目标系统没有响应或返回错误时，要进行的重试次数

1. 点击 提交 以保存该 Webhook。

创建任务

1. 导航到 系统 > 任务仪表板.
2. 点击 新任务 在左侧菜单中。
3. 配置任务：

   • 名称：为该任务提供一个描述性名称。
   • 描述（可选）：可为该任务存储附加信息，例如其用途、预期结果等。
   • 运行后删除任务：定义一次性激活；系统将在其运行一次后自动删除该任务。
   • 对象类型: Webhook
   • 对象： 选择上一步创建的 Webhook。
   • 动作: 发送
   • 消息：定义要发送到外部系统的载荷。- 默认载荷包含一个基本键值对，其值为字符串“Webhook”；如有需要，可删除或修改以创建所需载荷。

消息载荷中可使用变量：

• ${DATE} - 以完整字符串格式表示的当前日期/时间，例如 Thu, 16 Oct 2025 11:38:07 EDT
• ${TIMESTAMP} - 以数值形式表示的当前日期/时间（纪元时间），例如 1760629087
• ${RANDOM} - 随机生成的整数
• ${NAME} - 相关 VergeOS 对象的名称

1. 点击 提交 以保存该任务。

创建事件

1. 导航到 系统 > 任务仪表板.
2. 点击 新建事件 在左侧菜单中。
3. 配置事件：

   • 类型：选择将发生触发的 VergeOS 系统中相应区域。
   • 事件：事件列表会根据上面所选类型而变化。请选择将作为触发器的所需事件。
   • 选择特定对象实例或标签 以触发该事件：（某些所选类型，例如 警报 适用于通用级别，不提供标签或特定对象选项。）

     • 从下拉列表中选择该对象类型的一个特定实例（例如，所选类型为“Users”——请从中选择某个特定用户 用户 下拉列表；“虚拟机”是所选类型——从下拉列表中选择某个特定 VM 虚拟机 下拉列表。）

     或

     • 启用 使用标签 选项，并从下拉列表中选择一个可用标签，以便基于具有相应标签的对象来触发事件。（例如，如果“虚拟机”是所选类型，并且在 标签 下拉列表中选择了“production”，则事件触发器对应于任何分配了“production”标签的 VM。）
   • 任务：选择上一步创建的任务。
4. 点击 提交 以保存该事件。

---

版本兼容性：此功能适用于 VergeOS 26.0 及更高版本。