Webhook 檢測服務

支援開發者檢測 GPTBots webhook 服務可用性，支援開發者檢測目標代理所配置 webhook URL 可用性。

檢測代理所配置 webhook 服務可用性

GPTBots 支援開發者透過 API 檢測目標代理配置的所有 Webhook URL 可用性，其中包含接收「發送訊息」和「人工服務-webhook」所配置 webhook url 的可用性。當開發者呼叫本介面時，GPTBots 會自動檢測目前 API Key 所屬代理已配置的全部 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 識別目標代理，檢測該代理下所配置的 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 所屬代理已配置的全部 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	檢測結果列表，逐項回傳該代理每個已配置 Webhook 的檢測結果。未配置的 Webhook 不會出現在列表中。同一個代理配置了多個人工服務（handoff）元件時，每個元件各對應一條 `human_service` 結果。
type	string	Webhook 類型。`message`：接收代理回應訊息的 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	代理已刪除
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。