Webhook 检测服务

支持开发者检测GPTBots webhook服务可用性，支持开发者检测目标 Agent 所配置 webhook URL可用性。

检测Agent所配置webhook服务可用性

GPTBots 支持开发者通过 API 检测目标 Agent 配置的所有 Webhook URL可用性，其中包含接收「发送消息」和「人工服务-webhook」所配置 webhook url 的可用性。当开发者调用本接口时,GPTBots 会自动检测当前 API Key 所属 Agent 已配置的全部 Webhook URL，无需额外指定检测目标，并在响应中逐项返回每个 Webhook 的检测结果。
istest字段所涉及开发者所有的 Webhook 服务如下：

发送消息 API 响应消息到 webhook 的请求体中包含该字段,查看详情
接收人工服务对话请求通知和用户消息的请求体中包含该字段,查看详情

开发者的 Webhook 服务在收到请求时，应识别消息体中的 istest 字段：当 istest=true 时为可用性测试请求，不应将其作为真实业务消息处理（如不入库、不触发人工服务等），并返回 HTTP 状态码 200 即代表该 Webhook 可用。

请求方式

POST

调用地址

https://api-${endpoint}.gptbots.ai/v1/webhook/check

调用验证

详情参见 API 概述的鉴权方式说明。本接口通过 API Key 识别目标 Agent，检测该 Agent 下所配置的 Webhook。

请求

请求示例

curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/webhook/check' \ -H 'Authorization: Bearer ${API Key}' \ -H 'Content-Type: application/json'

                      
                      curl -X POST 'https://api-${endpoint}.gptbots.ai/v1/webhook/check' \
-H 'Authorization: Bearer ${API Key}' \
-H 'Content-Type: application/json'

此代码块在浮窗中显示

请求头

字段	类型	描述
Authorization	Bearer ${API Key}	使用`Authorization: Bearer ${API Key}`进行调用验证，请在 API 密钥页面获取密钥作为`API Key`。
Content-Type	application/json	数据类型，取值为 application/json。

请求参数

本接口无需传入请求参数，GPTBots 将自动检测当前 API Key 所属 Agent 已配置的全部 Webhook URL。

响应

响应示例

{ "results": [ { "type": "message", "component_id": null, "component_name": null, "webhook_url": "https://your_domain/webhook/message", "reachable": true, "http_status": 200, "latency_ms": 156 }, { "type": "human_service", "component_id": "665d88b03ce2b13cf2d57346", "component_name": "人工服务-售前", "webhook_url": "https://your_domain/presale/human/service/conversation/establish", "reachable": true, "http_status": 200, "latency_ms": 188 }, { "type": "human_service", "component_id": "665d88b03ce2b13cf2d57347", "component_name": "人工服务-售后", "webhook_url": "https://your_domain/aftersale/human/service/conversation/establish", "reachable": false, "http_status": 502, "latency_ms": 3000 } ] }

                      
                      {
  "results": [
    {
      "type": "message",
      "component_id": null,
      "component_name": null,
      "webhook_url": "https://your_domain/webhook/message",
      "reachable": true,
      "http_status": 200,
      "latency_ms": 156
    },
    {
      "type": "human_service",
      "component_id": "665d88b03ce2b13cf2d57346",
      "component_name": "人工服务-售前",
      "webhook_url": "https://your_domain/presale/human/service/conversation/establish",
      "reachable": true,
      "http_status": 200,
      "latency_ms": 188
    },
    {
      "type": "human_service",
      "component_id": "665d88b03ce2b13cf2d57347",
      "component_name": "人工服务-售后",
      "webhook_url": "https://your_domain/aftersale/human/service/conversation/establish",
      "reachable": false,
      "http_status": 502,
      "latency_ms": 3000
    }
  ]
}

此代码块在浮窗中显示

成功响应

字段	类型	描述
results	JSON Array	检测结果列表，逐项返回该 Agent 每个已配置 Webhook 的检测结果。未配置的 Webhook 不会出现在列表中。同一个 Agent 配置了多个人工服务（handoff）组件时，每个组件各对应一条 `human_service` 结果。
type	string	Webhook 类型。`message`：接收 Agent 响应消息的 Webhook；`human_service`：人工服务组件 webhook 模式所配置的 Webhook。
component_id	string	人工服务（handoff）组件的唯一标识 ID，用于区分配置了多个人工服务组件的场景。`message` 类型时为 `null`。
component_name	string	人工服务（handoff）组件的名称。`message` 类型时为 `null`。
webhook_url	string	被检测的 Webhook URL。
reachable	boolean	该 Webhook 是否可用。`true` 代表可用，`false` 代表不可用。
http_status	int	检测请求所返回的 HTTP 状态码；连接失败或超时时为 `null` 或 `0`。
latency_ms	long	检测请求的耗时（毫秒）。

可用性判断建议

GPTBots 按照标准消息格式向 Webhook URL 发送携带 istest=true 的检测请求，并以返回结果判定可用性：

情况	判定
返回 HTTP 状态码 `200`	该 Webhook 可用（`reachable=true`）
返回非 `200`（如 4xx/5xx）/ 请求超时 / 连接失败	该 Webhook 不可用（`reachable=false`）

失败响应

字段	类型	描述
code	int	错误码。
message	string	错误详情。

错误码

Code	Message
40000	参数错误
40127	开发者鉴权失败
40378	Agent 已删除
40379

GPTBots Webhook 服务状态检测

GPTBots 提供一个用于检测 webhook 服务的健康监测接口，开发者可调用该接口探测 GPTBots webhook 服务是否正常可用。接口返回 HTTP 状态码 200 且响应体为服务正常的英文标识（如 service is normal）则代表 GPTBots webhook 服务正常可用。该接口无需鉴权、返回明文。

请求方式

GET

调用地址

https://api.gptbots.ai/v1/webhook/service/health

请求示例

curl -X GET 'https://api.gptbots.ai/v1/webhook/service/health'

                      
                      curl -X GET 'https://api.gptbots.ai/v1/webhook/service/health'

此代码块在浮窗中显示

响应

GPTBots 服务正常可用时，返回 HTTP 状态码 200，且响应体返回服务正常的英文标识。

service is normal

                      
                      service is normal

此代码块在浮窗中显示

可用性判断建议

调用方仅需以 HTTP 状态码作为判据：

情况	判定
返回 `200` 且响应体为 `service is normal`	GPTBots 服务正常可用
返回非 `200`（如 5xx）/ 请求超时 / 连接失败	GPTBots 服务不可用

建议设置合理的请求超时（如 3~5 秒），并以固定频率轮询探测（QPM:3）；该接口免鉴权，调用时无需携带 API Key。