> For the complete documentation index, see [llms.txt](https://docs.verge.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.verge.io/automate-protect-and-extend/zh/zi-dong-hua/webhooks.md).

# Webhook

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

## Webhook 使用示例

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

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

## 配置步骤

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

* [**创建 Webhook**](#create-a-webhook)：定义目标 URL、身份验证方法，以及外部系统所需的任何自定义标头
* [**创建任务**](#create-a-task)：定义要传递的载荷
* [**创建事件**](#create-an-event)：指定将激活该任务的某个发生情况

{% hint style="success" %}
**模块化设计**

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

## 创建 Webhook

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

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

{% hint style="success" %}
**通常，您需要在目标系统上为您的 VergeOS 系统显式授予对此端点的访问权限**

**授权类型**

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

**标头**
{% endhint %}

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

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

4. 点击 **提交** 以保存该 Webhook。

## 创建任务

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

{% hint style="success" %}
**消息载荷中可使用变量：**

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

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

## 创建事件

1. 导航到 **系统** > **任务仪表板**.
2. 点击 **新建事件** 在左侧菜单中。
3. 配置事件：
   * **类型**：选择将发生触发的 VergeOS 系统中相应区域。
   * **事件**：事件列表会根据上面所选类型而变化。请选择将作为触发器的所需事件。
   * **选择特定对象实例或标签** 以触发该事件：（某些所选类型，例如 *警报* 适用于通用级别，不提供标签或特定对象选项。）

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

     **或**

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

***

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


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.verge.io/automate-protect-and-extend/zh/zi-dong-hua/webhooks.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.