API 參考

Webhook 端點

更新 Webhook 端點

更新 Webhook 端點。url 必須是絕對 HTTP(S) URL，正式環境建議 HTTPS；status 僅可為 active / inactive。subscribed_events 接受公開事件或 ["*"]；空 signing_secret 關閉簽章。

PATCHhttps://api.unifyport.ai/v1/webhook-endpoints/{endpoint_id}

呼叫前準備

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

PATCH 會取代 Webhook 設定。請提交所有需要保留的設定：省略 signing_secret 會停用簽章，省略 subscribed_events 會恢復接收全部公開事件，省略 retry_policy/max_attempts 會恢復預設重試 3 次。先讀取現有設定，並提供自行保存的簽章密鑰。

請求參數

請求標頭

X-Api-Key
string必填

工作區 API Key，工作區會由此標頭解析得到。

Content-Type
string必填

傳送 JSON 請求內容時請使用 application/json。

路徑參數

endpoint_id
string必填

用於該 webhook endpoints 路由的識別字。

請求內容

url
string必填

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

format: uri

status
string必填

端點狀態：active 或 inactive。

enum: active, inactive

subscribed_events[]
string[]

推送到此端點的公開標準事件；["*"] 代表全部公開事件，不包含 provider.raw_event。

signing_secret
string

可選的 Webhook 簽章密鑰，範例中請使用佔位符。

retry_policy
object

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

max_attempts
integer

首次投遞後的重試次數，範圍為 0 到 5。

如何理解結果

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

回應 200 OK

{
  "request_id": "<REQUEST_ID>",
  "data": {
    "id": "we_example",
    "url": "https://example.com/webhook-updated",
    "status": "inactive",
    "subscribed_events": [
      "message.delivered",
      "message.read"
    ],
    "signing_enabled": false,
    "retry_policy": {
      "max_attempts": 1
    }
  }
}

回應內容

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

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

400

請求錯誤

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

401

未授權

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

失敗後如何處理

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

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