API 參考

Webhook 端點

列出 Webhook 端點

列出目前工作區嘅 Webhook 端點，包括訂閱事件、簽名狀態、端點狀態同重試政策。

GEThttps://api.unifyport.ai/v1/webhook-endpoints

呼叫前準備

在伺服器端使用資源所屬工作區的 X-Api-Key，執行範例前替換所有預留位置。

請求參數

請求標頭

X-Api-Key
string必填

工作區 API Key，工作區會由呢個標頭解析得出嚟。

請求內容

呢個介面唔需要 JSON 請求內容。

如何理解結果

設定成功不代表事件已投遞。觸發相關事件，在接收端驗證請求、簽章及回應。

回應 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": [
    {
      "id": "we_example",
      "url": "https://example.com/webhook",
      "status": "active",
      "subscribed_events": [
        "message.received"
      ],
      "signing_enabled": true,
      "retry_policy": {
        "max_attempts": 3
      }
    }
  ]
}

回應內容

id
string

Webhook 端點識別碼（we_...）。

url
string

接收 webhook 派送嘅絕對 HTTP(S) URL；正式環境建議 HTTPS。

format: uri

status
string

端點狀態：active 或者 inactive。

enum: active, inactive

subscribed_events[]
string[]

派去呢個端點嘅公開標準事件類型；["*"] 即係全部公開事件，唔包括 provider.raw_event。

signing_enabled
boolean

設咗簽名密鑰、派送會簽名嗰陣會係 true。

retry_policy
object

API 回傳嘅重試設定。max_attempts 統計首次投遞之後嘅重試次數，預設 3，範圍 0 到 5。

max_attempts
integer

已設定嘅首次投遞後重試次數，範圍係 0 到 5。

回應

200

200 OK

請求成功，回應內容嘅例子如上。

401

未授權

X-Api-Key 請求標頭缺少或者無效。

500

伺服器錯誤

服務遇到咗未預期嘅錯誤。

失敗後如何處理

檢查 HTTP 狀態和 error.code/numeric_code，保留 request_id。依原因修正參數、繼續授權或檢查狀態。重試傳送及寫入前確認上次結果，避免重複操作。 錯誤碼參考

invalid_request · 10000 · 400
檢查必填欄位、格式與渠道條件，修正請求後再呼叫。
invalid_api_key · 11001 · 401
檢查 X-Api-Key 與工作區是否有效。