Webhook

Webhook 是用于接收事件通知的 HTTP 端点。当特定事件发生时，系统会主动向预定义的 URL（Webhook URL）发送 HTTP 请求。Webhook 通常用于通知外部系统状态变更或异步任务结果。

常见使用场景

尽管从技术上讲 Webhook 只是一个 HTTP 端点，但它的使用方式有所不同：

Webhook：系统主动调用外部 URL

常规端点：客户端向系统发送请求

在你的 Apidog 项目中，点击左侧边栏中的 "+" 图标，然后选择 "New Other Protocol APIs" → "Webhook"。

创建 Webhook 后，在编辑器中填写以下字段：

字段	描述
请求方法	通常为 `POST`
Webhook 名称	显示在 API 文档和 OpenAPI 导出中（例如 `order`）
调试 URL	可选。用于发送测试请求的实际 URL（仅用于测试，不会包含在文档中）
其他信息	请求主体、头部以及其他配置

完成所有必填字段后，点击 "Save"。

Webhook 调试会模拟一次事件触发，以验证外部服务是否正确接收到请求。

要调试 Webhook：

将你的 Webhook URL 输入到 Debug URL 字段中

点击 "Send" 以模拟一次 Webhook 调用

Webhook 文档包含 Webhook 名称、请求方法和请求主体等详细信息。这可以帮助用户更容易理解某个事件发生时将发送哪类数据。

Debug URL 隐私

Debug URL 将不会包含在文档或 OpenAPI 导出中——它仅用于内部测试。

在导出的 OpenAPI 文件中，Webhook 端点列在 webhooks 字段下，这不同于常规端点所在的 paths 字段。

为什么要在文档中单独定义 Webhook？

根据 OpenAPI 3.1 规范：

常规端点定义在 paths 字段下

Webhook 端点定义在 webhooks 字段下

这种清晰的分离可以确保：

常规端点由外部客户端调用，用于执行操作或获取数据

Webhook 由系统触发，用于通知外部服务

在 Apidog 中，Webhook 被视为一种独立的端点类型，以准确反映这种方向上的差异，并确保在 OpenAPI 导出中使用正确的格式。

示例：

/orders 是客户端使用的常规端点

orderPaid 是系统在订单成功支付时触发的 Webhook

Webhook 只是一个常规端点吗？

Debug URL 会显示在我的 API 文档中吗？