使用手冊 取消

Acrobat Sign Webhook 概觀

 

Adobe Acrobat Sign 指南

新功能

開始使用

管理

傳送、簽署與管理合約

進階合約功能與工作流程

與其他產品整合

Acrobat Sign 開發人員

支援與疑難排解

概覽

Webhook 是一種由使用者定義的 HTTPS 請求,會在已訂閱的事件於來源網站 (以此例來說就是 Adobe Acrobat Sign) 上發生時觸發。

實際上,Webhook 只是一種會接受資料或串流資料的 REST 服務。

Webhook 是為了用於在推送模型中提供服務對服務通訊

當已訂閱的事件觸發時,Acrobat Sign 會建構具有 JSON 內文的 HTTPS POST,並將其傳遞到指定的 URL。

設定 Webhook 之前,請先確定您的網路能接受功能所需的 IP 範圍

 

與過去的回呼方法相比,Webhook 具有多種優點,其中包括:

  • 管理員可以啟用其 Webhook,無需由 Acrobat Sign 支援以列出回呼 URL
  • Webhook 在資料的「新鮮度」、通訊效率和安全性方面都比較好。不需要輪詢
  • Webhook 可輕鬆使用不同層級的範圍 (帳戶/群組/使用者/資源)。 
  • Webhook 是更現代化的 API 解決方案,能夠更簡單直覺地設定現代化的應用程式
  • 每個作用範圍 (帳戶/群組/使用者/資源) 皆可設置多個 Webhook,但回呼必須是唯一的
  • Webhook 允許選擇要傳回的資料,其中回呼是一種「全有或全無」解決方案
  • 可設置隨 Webhook 一起攜帶的中繼資料 (基本或詳細)
  • 更容易依需要建立、編輯或禁用 Webhook,因為 UI 完全在管理員的控制之下。
註解:

本文件主要聚焦於 Acrobat Sign 網路應用程式 (之前稱為 Adobe Sign) 中 Webhook 的 UI。

尋求 API 詳細資訊的開發人員,可在以下位置找到更多資訊:

必要條件

您必須允許 Webhook 的 IP 範圍通過您的網路安全性,服務才能運作。

REST v5 中的舊版回呼 URL 服務使用與 Webhook 服務相同的 IP 範圍。

管理員可登入 Adobe Admin Console 以新增使用者。登入後,瀏覽至管理員選單,並向下捲動至 Webhook

使用方式

管理員首先需要有 Webhook 服務,準備好接受來自 Acrobat Sign 的傳入推送。這部份有許多選項,只要服務能夠接受 POST 和 GET 請求,Webhook 就會成功。

服務到位後,Acrobat Sign 管理員便可從 Acrobat Sign 網站上「帳戶」選單中的 Webhook 介面建立新的 Webhook。

管理員可以設定 Webhook 以觸發合約、網頁表單 (Widget) 或大量傳送 (MegaSign) 事件。亦可透過 API 設定資料庫範本 (資料庫文件) 資源。

Webhook 的範圍可以包括整個帳戶,或是透過管理介面的各個群組。透過選擇「使用者」或「資源」範圍,API 可提供更多的精細度。

推送至 URL 的資料類型是可設定的,且可包括如合約資訊、參與者資訊、文件資訊等。

設定並儲存好 Webhook 後,每次已訂閱的事件觸發時,Acrobat Sign 就會將新的 JSON 物件推送到已定義的 URL。除非您要更改事件觸發條件或 JSON 裝載,否則不需要持續操作 Webhook。

驗證 Webhook URL 的目的

在成功註冊 Webhook 之前,Acrobat Sign 會驗證註冊請求中提供的 Webhook URL 是否有意接收通知。為此,當 Acrobat Sign 收到新的 Webhook 註冊請求時,會先向該 Webhook URL 提出驗證請求。 此驗證請求是發送到Webhook URL的HTTPSGET請求。 此請求具有自訂 HTTP 標頭 X-AdobeSign-ClientId。此標頭中的值,會設定為請求建立/註冊該 Webhook 之 API 應用程式的用戶端 ID (應用程式 ID)。為了成功註冊 Webhook,Webhook URL 必須以 2XX 回應代碼回應此驗證請求,「而且」還「必須」以下列兩種方法的其中一種,傳回相同的用戶端 ID 值:

  • 在回應標頭 X-AdobeSign-ClientId 中。這就是於請求中傳遞,並在回應中傳回的同一標頭。
  • 或是在 JSON 回應內文中,其中含有 xAdobeSignClientId 鍵,且其值與在請求中傳送的用戶端 ID 相同。

要成功回應 (2XX 回應代碼) 並驗證標頭或回應內文中的用戶端 ID,才算成功註冊 Webhook。此驗證請求的目的,是要證明您的 Webhook URL 確實希望在該 URL 上接收通知。如果意外輸入錯誤的 URL,則 URL 無法正確回應意圖請求的驗證,且 Acrobat Sign 不會向該 URL 發送任何通知。此外,Webhook URL 還可以驗證它只透過由特定應用程式註冊的 Webhook 接收通知。這可藉由驗證在 X-AdobeSign-ClientId 標頭中傳遞的應用程式用戶端 ID 來完成。如果 Webhook URL 無法識別該用戶端 ID,則它「必定不使用」成功回應代碼回應,而 Acrobat Sign 會注意該 URL 並未註冊為 Webhook。

系統將在以下的情況下驗證 Webhook URL 呼叫:

  • 註冊 Webhook:如果此 Webhook URL 呼叫驗證失敗,就不會建立 Webhook。
  • 更新 Webhook:「非作用中」到「作用中」:如果此 Webhook URL 呼叫驗證失敗,Webhook 的狀態就不會更改為「作用中」。

如何回應 Webhook 通知

Acrobat Sign 會在發送到 Webhook URL 的每個 Webhook 通知請求中,執行目的的隱含驗證。因此,每個 Webhook 通知 HTTPS 請求還包含名為 X-AdobeSign-ClientId 的自訂 HTTP 標頭。此標頭的值是建立 Webhook 的應用程式之用戶端 ID (應用程式 ID)。我們只會在以下情況下將 Webhook 通知視為已成功傳送:若,且若傳回成功回應 (2XX 回應代碼),並在 HTTP 標頭 (X-AdobeSign-ClientId) 中或在具有鍵為 xAdobeSignClientId 且值為同一用戶端 ID 的 JSON 回應內文中,傳送用戶端 ID,否則我們會重新嘗試將通知傳送到 Webhook URL,直到重試次數用盡為止。

如何啟用或停用

針對企業層級帳戶,預設啟用對 Webhook 功能的存取權。

群組層級管理員可建立/控制僅在其群組內運作的 Webhook。

如要存取「Webhook」頁面,可在「管理」選單的左側邊欄找到。

瀏覽至「webhook」標籤

基於並行的速率限制

Webhook (及回呼) 的建立與通知事件的數量,受限於從 Acrobat Sign 系統主動傳送給客戶的並行通知數量。此限制適用於帳戶,以包含帳戶中的所有群組。
此類速率限制可防止一個設計不良的帳戶消耗不成比例的伺服器資源量,進而對該伺服器環境中的所有其他客戶造成負面影響。

系統已計算每個帳戶同時發生的事件數,以確保在最短時間內,Webhook 表現良好的帳戶都能收到其通知,且應該極少發生由於請求太多而導致通知延遲的情況。目前的臨界值為:

動作
(事件)

最大
同時發生
事件數

說明

建立 Webhook

10

每個帳戶最多可有 10 個並行的 Webhook 建立請求。
若請求數超過此限制,會出現 429 TOO_MANY_REQUESTS 回應代碼。

Webhook/回呼通知

30

每個帳戶最多可有 30 個並行的 Webhook 與回呼通知。
超過此限制的通知會根據指數輪詢重試,直到送達為止。

最佳實務

  • 訂閱特定的必要事件,以限制對伺服器的 HTTPS 請求數量 - Webhook 設定得越明確,您需要過濾的量就愈少
  • 避免重複 - 如果您有多個應用程式共用同一個 Webhook URL,且同樣的使用者對應至各個應用程式,則同一事件將多次 (每個應用程式一次) 發送到您的 Webhook。在某些情況下,您的 Webhook 可能會收到重複事件。您的 Webhook 應用程式應要能容忍此情況,並藉由事件 ID 消除重複資料。
  • 始終快速回應 Webhook - 您的應用程式只有五秒鐘可回應 Webhook 請求。驗證請求的部分很少有問題,因為您的應用程式不需要做任何實際的工作來回應。但在通知請求的部分,您的應用程式通常會執行一些需要時間的操作來回應請求。建議您在個別的執行緒上作業,或是以非同步的方式使用佇列,以確保您能在五秒內回應
  • 管理並行 - 當使用者快速連續進行多項變更時,您的應用程式可能會在差不多的時間收到同一使用者的多個通知。如果您對於並行的管理方式不夠小心,您的應用程式便可能會多次處理同一使用者的相同變更。為了利用 Acrobat Sign 的 Webhook,您必須對資訊的使用情況有清楚的理解。請務必提出以下問題:
    • 您要在裝載中傳回哪些資料?
    • 誰將存取此資訊?
    • 將產生哪些決定或報告?
  • 接收已簽署文件的建議 - 在決定如何於文件管理系統中接收 Acrobat Sign 的已簽署 PDF 時,需要考慮幾個因素。

儘管在建立 Webhook 時,您可以選取「合約已簽署文件」選項,不過您也可以考慮在收到觸發事件 (例如合約狀態完成) 時,使用 Acrobat Sign API 擷取文件。

注意事項…

JSON 大小限制

JSON 裝載的大小限制為 10 MB。

如果事件產生較大的裝載,則雖會觸發 Webhook,但如果請求中存在條件參數屬性時,會刪除該條件參數屬性以縮減裝載的大小。 

當發生此情況時,系統將在回應中傳回「ConditionalParametersTrimmed」以通知用戶端「 conditionalParameters 」資訊已遭移除。

conditionalParametersTrimmed」是陣列物件,包含已剪除的各個金鑰的資訊。

截斷處理將按照以下順序進行:

  • includeSignedDocuments
  • includeParticipantsInfo
  • includeDocumentsInfo
  • includeDetailedInfo

首先會截斷已簽署的文件,然後是參與者資訊、文件資訊,最後則是詳細資訊。

例如,如果合約完成事件也包括已簽署的文件 (64 位元編碼),或是合約具有多個表單欄位時,便可能發生這種情況

Webhook 通知

Acrobat Sign Webhook 會傳送通知給合約的傳送者,以及設定於傳送合約的群組中的任何 Webhook。帳戶範圍的 Webhook 會接收所有事件。

當偵聽服務關閉時重試

如果 Webhook 的目標 URL 因任何原因停止,則 Adobe Sign 會將 JSON 排入佇列,然後在 72 小時內以漸進式循環重試推送。

未傳遞的事件將保留在重試佇列中,系統會在接下來的 72 小時內盡全力按照通知發生的順序傳遞通知。

重試傳送通知的策略是將嘗試的間隔時間變更兩倍,從間隔 1 分鐘開始,到每隔 12 小時,結果就是在 72 小時內重試 15 次。

如果 Webhook 接收器在 72 小時內未能回應,且在過去七天內都未曾成功發送通知,則系統便會停用 Webhook。直到 Webhook 再次啟用前,系統都不會向此 URL 發送任何通知。

在 Webhook 停用到之後再次啟用之間的所有通知,都會遺失。

更快、更輕鬆地獲得協助

新的使用者?