這個頁面做什麼
「官網內容管理」裡的資料新增、更新、封存或還原時,好辦會通知你指定的網址,讓官網或其他服務即時更新,不必定時重新讀取。頁面分成「Webhook 設定」與「傳送紀錄」兩個子列表。
這個頁面在「設定 › 整合與開發」,只有擁有者與管理員可以開啟。內容 API 與 Webhook 屬於高級方案;目前方案不含時,頁面會提示升級,無法新增 Webhook,資料變更也不會傳送(傳送紀錄會註明原因,升級後可以重送)。事件格式與簽章驗證方式在同一區的「API 文件」。
新增 Webhook
按「新增 Webhook」,填寫:
名稱:方便辨識,例如「官網更新」。
Webhook URL:接收通知的網址,必須以 https:// 開頭,不能包含帳號密碼、「#」之後的片段,或 443 以外的連接埠。部分環境只開放特定的接收主機,欄位會列出允許的主機;尚未開放時頁面會提示,暫時無法新增。
授權資料類型:只通知勾選的內容類型,至少選一種。
新增後會顯示一次性密鑰,用來驗證通知確實來自好辦。請保存在接收服務的密鑰設定;關閉前會再確認一次,關閉後無法再查看。
每家公司最多 10 個啟用中的 Webhook。同一個接收網址已有啟用中的 Webhook 訂閱相同資料類型時不能再新增,以免同一事件傳送兩次;要更換密鑰時,請先停用原本的再新增。
停用 Webhook
在「Webhook 設定」按「停用」,或打開 Webhook 詳情,從「⋯」選「停用 Webhook」,再確認後,不再接收資料變更通知。詳情會更新為停用,無法重複停用。停用無法重新啟用,需要時請新增一個 Webhook(會產生新的密鑰)。停用前還沒送出的通知不會再傳送。
傳送紀錄與重送
每次資料變更的通知都會列在「傳送紀錄」,寫出是哪個 Webhook、哪一種資料與變更(內容、主要分類或標籤),以及已嘗試的次數。
狀態 | 說明 |
|---|---|
等待傳送 | 已排入佇列,稍後傳送。 |
處理中 | 正在傳送。 |
已完成 | 接收網址回應成功(2xx)。 |
失敗 | 自動重試後仍未成功,或這次不會傳送;第二行顯示原因。 |
通知不會跟隨轉址:接收網址回傳 3xx 轉址時視為沒有成功,請填寫最終的網址。接收網址沒有回應成功時,會自動重試,共嘗試 3 次,每次間隔約 30 秒;仍失敗時標為「失敗」,可以按「重送」再傳一次。以下情況不會傳送,直接標為「失敗」並寫出原因:
找不到這筆資料變更。
內容類型已停用。
目前方案不含 Webhook(升級後可以重送)。
Webhook 已停用,或不再訂閱這個內容類型。
接收網址的主機已不在允許的主機清單。
公司暫停使用期間。
失敗的傳送紀錄也可以從詳情的「⋯ › 重送」處理。已停用的 Webhook 或目前方案不含 Webhook 時不能重送,畫面會說明原因,詳情的重送操作會停用。接收端請以事件的識別碼去重,因為重試或重送可能讓同一事件送達不只一次。
新增時連線中斷
按「新增 Webhook」後連線中斷,可能已經新增但沒收到密鑰。這時再按一次「新增 Webhook」即可確認:若前一次已新增,會再顯示同一組密鑰,不會多新增一個。
目前限制
只通知官網內容管理的資料變更,報價、請款等商務資料沒有 Webhook。
接收網址、授權資料類型建立後不能修改,請新增一個再停用舊的。
密鑰只在新增時顯示,好辦也無法替你查回。