Webhook 端點

建立 Webhook 端點

建立 Webhook 接收端。url 一定要係絕對 HTTP(S) URL，正式環境建議 HTTPS；status 淨係可以係 active / inactive。subscribed_events 接受公開事件或 ["*"]，max_attempts 範圍 0..5。帳號端點建立為 active 時，如果同一帳號已有其他 active 端點，會回傳 409 account_webhook_already_exists（40008）。通話事件權限由工作區 is_beta 控制。內測工作區的 subscribed_events 為 *、空陣列或省略時包含通話事件；具體事件清單只匹配列出的事件。非內測工作區可使用通配訂閱，但不會收到通話事件；明確訂閱通話事件仍傳回 403 beta_feature_not_enabled。每次投遞、重試及死信重放都重新核驗資格，查詢失敗不放行；一般 message.* 通話記錄獨立，不受影響。

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

支援渠道

all

呼叫前準備

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

建立或重新啟用帳號獨立端點時，同一 account_id 只允許一個 active 端點；衝突回傳 409 account_webhook_already_exists（40008）。inactive 帳號端點和工作區端點可有多個。原 active 端點維持 active 時允許更新，歷史多 active 設定也適用。

參數從哪裡取得

account_id: 從建立或查詢帳號的回應取得 data.id。帳號屬於 X-Api-Key 對應的工作區。攞帳號

請求

curl -X POST "https://api.unifyport.ai/v1/webhook-endpoints" \
  -H "X-Api-Key: <YOUR_API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "url": "https://example.com/webhook",
  "status": "active",
  "subscribed_events": ["*"],
  "signing_secret": "<WEBHOOK_SIGNING_SECRET>"
}'

請求參數

請求標頭

X-Api-Key

string必填

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

Content-Type

string必填

發送 JSON 請求內容嘅時候請用 application/json。

請求內容

account_id

string

body 中可選嘅公開帳號 ID，例如 acc_example。建立時用嚟綁定帳號，省略就建立工作空間端點；更新時只驗證原有綁定，省略就保留現有歸屬。唔可以切換帳號、將工作空間端點改為帳號端點或清除綁定。唔接受 query、null、空字串、純空白字串或重複欄位。欄位名稱必須精確使用 account_id；body 或 query 中嘅大小寫變體及歸屬唔匹配會回傳 400 invalid_request。明確指定嘅帳號唔存在或唔屬於目前工作空間會回傳 404 account_not_found (20020)。帳號獨立設定優先於工作空間設定；停用或冇訂閱某類事件唔會回退至工作空間。刪除最後一個獨立端點後，之後嘅首次投遞會恢復繼承。啟用衝突只檢查同一 account_id 嘅其他 active 端點；工作空間端點唔受呢個限制，具體條件見 status。

minLength: 1 · pattern: \S

url

string必填

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

format: uri

status

string必填

端點狀態：active 或 inactive。建立 active 帳號端點或由 inactive 改為 active 時，如果同一帳號已有其他 active 端點，會回傳 409 account_webhook_already_exists（40008）。inactive 帳號端點同工作空間端點都可以設定多個。原本 active 端點保持 active 嘅更新仍然可以執行，包括歷史多 active 設定；歷史端點唔會自動清理。

enum: active, inactive

subscribed_events[]

string[]

公開標準事件訂閱。省略、空陣列或包含 * 表示接收全部公開事件，包括新增嘅 contact.updated，但唔包括 provider.raw_event。只需要指定事件時請明確列出事件名。

signing_secret

string

可選嘅 Webhook 簽名密鑰，例子入面請用佔位符。

retry_policy

object

可選嘅重試政策。max_attempts 係首次投遞之後嘅重試次數，預設 3，範圍 0 到 5；0 代表只做首次投遞。

max_attempts

integer

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

如何理解結果

檢查回傳設定。驗證投遞前，端點須為 active 並已訂閱相關事件；僅在 signing_enabled 為 true 時驗證簽章。收到事件後先儲存，再回傳 2xx 確認投遞。

回應 201 Created

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

回應內容

id

string

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

account_id

string

帳號獨立端點嘅公開帳號 ID；工作空間端點會省略呢個欄位，唔會回傳 null。

minLength: 1

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。

回應

201

201 Created

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

400

請求錯誤

請求內容、路徑或者參數無效。

401

未授權

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

403

禁止存取

請求已識別，但唔允許執行呢個操作。

404

搵唔到資源

搵唔到請求嘅資源；請結合 error.code 同目前操作核對。

409

衝突

目前操作同現有嘅渠道帳號或者資源衝突。

500

伺服器錯誤

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

失敗後如何處理

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

請按目前操作一併讀取 HTTP 狀態、error.code 同 error.numeric_code。數字碼以字串處理。保留 request_id 排查；佢唔係冪等鍵或任務識別碼。

invalid_request · 10000 · 400

檢查 JSON 請求內容與必填欄位。

處理與重試: 按目前操作同渠道條件修正參數後再請求。重複提交相同嘅無效請求唔會解決錯誤。

示意 JSON；message 會隨實際原因變化 · 400 · 10000

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_request",
    "numeric_code": "10000",
    "message": "Invalid request parameters"
  }
}

invalid_target_workspace · 11003 · 400

工作區覆寫目標為空或格式無效。請移除覆寫請求標頭，改用目標工作區所屬嘅 API Key。

觸發條件: 適用於帶有 X-Workspace-Id 工作區覆寫請求標頭嘅請求。

處理與重試: 按目前操作同渠道條件修正參數後再請求。重複提交相同嘅無效請求唔會解決錯誤。

示意 JSON；message 會隨實際原因變化 · 400 · 11003

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_target_workspace",
    "numeric_code": "11003",
    "message": "Invalid target workspace"
  }
}

invalid_api_key · 11001 · 401

檢查 API Key 是否正確且已啟用。

處理與重試: 保留 request_id 同結構化錯誤碼，先排查目前操作，再決定下一步。

示意 JSON；message 會隨實際原因變化 · 401 · 11001

{
  "request_id": "req_example",
  "error": {
    "code": "invalid_api_key",
    "numeric_code": "11001",
    "message": "Invalid API key"
  }
}

missing_api_key · 11000 · 401

請加入 X-Api-Key 請求標頭。

處理與重試: 保留 request_id 同結構化錯誤碼，先排查目前操作，再決定下一步。

範例 · 401 · 11000

{
  "request_id": "req_xxx",
  "error": {
    "code": "missing_api_key",
    "numeric_code": "11000",
    "message": "Missing X-Api-Key header"
  }
}

beta_feature_not_enabled · 41002 · 403

工作區需要內測資格，才可使用通話介面及明確訂閱通話事件。

處理與重試: 保留 request_id 同結構化錯誤碼，先排查目前操作，再決定下一步。

範例 · 403 · 41002

{
  "request_id": "req_example",
  "error": {
    "code": "beta_feature_not_enabled",
    "numeric_code": "41002",
    "message": "Beta feature not enabled"
  }
}

workspace_override_forbidden · 11002 · 403

請求嘗試使用呢個 API Key 無權使用嘅工作區覆寫。請移除覆寫請求標頭，改用目標工作區所屬嘅 API Key。

觸發條件: 適用於帶有 X-Workspace-Id 工作區覆寫請求標頭嘅請求。

處理與重試: 保留 request_id 同結構化錯誤碼，先排查目前操作，再決定下一步。

示意 JSON；message 會隨實際原因變化 · 403 · 11002

{
  "request_id": "req_example",
  "error": {
    "code": "workspace_override_forbidden",
    "numeric_code": "11002",
    "message": "Workspace override is not allowed"
  }
}

account_not_found · 20020 · 404

核對 account_id，並使用帳號所屬工作區的 X-Api-Key。此工作區下未找到的帳號無法使用目前 Key 存取。

處理與重試: 核對目標識別碼、資源歸屬同目前工作區。唔好將已確認缺少或無法存取嘅目標當成暫時服務故障自動重試。

示意 JSON；message 會隨實際原因變化 · 404 · 20020

{
  "request_id": "req_example",
  "error": {
    "code": "account_not_found",
    "numeric_code": "20020",
    "message": "Account not found"
  }
}

target_workspace_not_found · 11004 · 404

覆寫指定嘅工作區不存在或不可用。請核對工作區歸屬，移除覆寫請求標頭並使用目標工作區 API Key；重複請求唔會增加存取權限。

觸發條件: 適用於帶有 X-Workspace-Id 工作區覆寫請求標頭嘅請求。

處理與重試: 核對目標識別碼、資源歸屬同目前工作區。唔好將已確認缺少或無法存取嘅目標當成暫時服務故障自動重試。

示意 JSON；message 會隨實際原因變化 · 404 · 11004

{
  "request_id": "req_example",
  "error": {
    "code": "target_workspace_not_found",
    "numeric_code": "11004",
    "message": "Target workspace not found"
  }
}

account_webhook_already_exists · 40008 · 409

使用 account_id 列出此帳號的獨立端點，更新既有 active 端點。需要切換時，先停用舊 active 端點，再啟用其他端點；不要自動重試建立或重新啟用。

處理與重試: 重新提交前先讀取端點設定同帳號歸屬。PATCH 會取代設定，保留所需訂閱、簽名設定及重試策略。active 名額衝突時更新已有端點，或先停用舊端點再啟用其他端點。

範例 · 409 · 40008

{
  "request_id": "req_example_webhook_conflict",
  "error": {
    "code": "account_webhook_already_exists",
    "numeric_code": "40008",
    "message": "Account already has an active webhook endpoint"
  }
}

create_webhook_endpoint_failed · 40001 · 500

建立 Webhook 端點：未分類錯誤中斷今次改動，需要確認資源最終狀態。

示意 JSON；message 會隨實際原因變化 · 500 · 40001

{
  "request_id": "req_example",
  "error": {
    "code": "create_webhook_endpoint_failed",
    "numeric_code": "40001",
    "message": "Failed to create webhook endpoint"
  }
}