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"
  }
}