使用手冊取消

設定 Webhook

搜尋

上次更新時間 2024年1月10日 | 亦適用於 Adobe Acrobat Sign

Adobe Sign

開啟應用程式

Adobe Acrobat Sign 整合
新增功能
產品版本與生命週期
適用於 Salesforce 的 Acrobat Sign
適用於 Microsoft 的 Acrobat Sign
1. 適用於 Microsoft 365 的 Acrobat Sign
  1. 安裝指南
2. 適用於 Outlook 的 Acrobat Sign
  1. 使用手冊
3. 適用於 Word/PowerPoint 的 Acrobat Sign
  1. 使用手冊
4. 適用於 Teams 的 Acrobat Sign
5. 適用於 Microsoft PowerApps 和 Power Automate 的 Acrobat Sign
  1. 使用手冊
  2. 版本注意事項
6. 適用於 Microsoft Search 的 Acrobat Sign 連接器
  1. 使用手冊
  2. 版本注意事項
7. 適用於 Microsoft Dynamics 的 Acrobat Sign
8. 適用於 Microsoft SharePoint 的 Acrobat Sign
適用於 ServiceNow 的 Acrobat Sign
適用於 HR ServiceNow 的 Acrobat Sign
1. 安裝指南 (已淘汰)
適用於 SAP SuccessFactors 的 Acrobat Sign
適用於 Workday 的 Acrobat Sign
適用於 NetSuite 的 Acrobat Sign
1. 安裝指南
2. 版本注意事項
適用於 SugarCRM 的 Acrobat Sign
適用於 VeevaVault 的 Acrobat Sign
適用於 Coupa BSM Suite 的 Acrobat Sign
1. 安裝指南
適用於 Zapier 的 Acrobat Sign
Acrobat Sign 開發人員文件

概覽

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

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

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

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

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

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

註解：

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

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

REST v6 詳細資訊

使用方式

管理員首先需要有 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，直到重試次數用盡為止。

如上所述，在 Sign 的每個通知請求中都包含標頭「X-AdobeSign-ClientId」，而此標頭的值 (用戶端 ID) 應以如下兩種方式的其中一種，於回應中傳回：

1. HTTP 標頭 X-AdobeSign-ClientId 和作為此用戶端 ID 的值

擷取用戶端 ID 的 Javascript 程式碼範例，先驗證，然後在回應標頭中將之傳回
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Validate it if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response header response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; // default value }

擷取用戶端 ID 的 PHP 程式碼範例，先驗證，然後在回應標頭中將之傳回
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response header header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // default value } ?>

2. 具有金鑰為 xAdobeSignClientId，且值為同一用戶端 ID 的 JSON 回應內文

擷取用戶端 ID 的 Javascript 程式碼範例，先驗證，然後在回應內文中將之傳回
// Fetch client id var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //Validate it if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var responseBody = { "xAdobeSignClientId" : clientid // Return Client Id in the body }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; }

擷取用戶端 ID 的 Javascript 程式碼範例，先驗證，然後在回應內文中將之傳回

// Fetch client id

var clientid = request.headers['X-ADOBESIGN-CLIENTID'];

//Validate it

if (clientid ==="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

var responseBody = {

"xAdobeSignClientId" : clientid // Return Client Id in the body

};

response.headers['Content-Type'] = 'application/json';

response.body = responseBody;

response.status = 200;

}

擷取用戶端 ID 的 PHP 程式碼範例，先驗證，然後在回應內文中將之傳回
<?php // Fetch client id $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //Validate it if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { //Return it in response body header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // default value } ?>

擷取用戶端 ID 的 PHP 程式碼範例，先驗證，然後在回應內文中將之傳回

<?php

// Fetch client id

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//Validate it

if($clientid == "BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

//Return it in response body

header("Content-Type: application/json");

$body = array('xAdobeSignClientId' => $clientid);

echo json_encode($body);

header("HTTP/1.1 200 OK"); // default value

}

JSON 的回應內文範例
{ "xAdobeSignClientId": "BGBQIIE7H253K6" }

必要條件

您需要：

獲授權可建立 Azure 函式應用程式的 Microsoft 帳戶
既有的 Azure 函式應用程式，您可以使用 https://docs.microsoft.com/zh-tw/azure/azure-functions/functions-create-first-azure-function 來建立
Javascript 的基本知識，以便能以您選擇的任何語言理解並編寫程式碼

建立做為 Acrobat Sign Webhook 的 Azure 函式觸發程式的步驟

建立 Javascript HTTP 觸發函式：

1. 用您的 Microsoft 帳戶登入 https://portal.azure.com/

2. 開啟在「函式應用程式」標籤下顯示的 Azure 函式應用程式。

這會開啟 Azure 函式應用程式清單：

3. 選擇要在其中建立新函式的應用程式

4. 按一下「建立 (+)」按鈕以建立新的 Azure 函式

5. 選取 Webhook + API 作為情境，選取 Javascript 作為語言

6. 按一下「建立此函式」

如此即建立有能力處理傳入 API 請求的新函式。

新增邏輯以註冊 Acrobat Sign Webhook

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

您有兩種選項可遵循：

選項 1：在 X-AdobeSign-ClientId 中傳遞用戶端 ID 作為回應標頭

在回應標頭中傳遞 X-AdobeSign-ClientId。這就是於請求中傳遞，且必須在回應中傳回的同一個標頭。

以下列程式碼取代 Index.js 檔案：

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Validate that the incoming ClientID is genuine

if (clientId === '123XXX456') {

context.res = {

// status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

body: "Notification Accepted",

headers : {

'x-adobesign-clientid' : req.headers['x-adobesign-clientid']

}

};

}

else {

context.res = {

status: 400,

body: "Opps!! Illegitimate Call identified"

};

}

context.done();

};

透過模擬請求來測試行為：

1. 按一下右上角的「測試」按鈕

2. 模擬假請求

雖然上面未顯示回應標頭，但您可透過 postman/DHC 或任何其他服務，對其進行模擬以觀察。

選項 2：使用 xAdobeSignClientId 金鑰在回應內文中傳遞用戶端 ID

在 JSON 回應內文中，其中含有 xAdobeSignClientId 金鑰，且其值與在請求標頭中傳送的用戶端 ID 相同。

以下列程式碼取代 Index.js 檔案：

module.exports = function (context, req) {

var clientId = req.headers['x-adobesign-clientid'];

// Validate that the incoming ClientID is genuine

if (clientId === '123XXX456') {

context.res = {

// status: 200, /* Defaults to 200 */ // any 2XX response is acceptable

body: {

'xAdobeSignClientId' : clientId

headers : {

'Content-Type' : 'application/json'

}

};

}

else {

context.res = {

status: 400,

body: "Opps!! Illegitimate Call identified"

};

}

context.done();

};

透過模擬請求來測試行為

1. 按一下右上角的「測試」按鈕

2. 模擬假請求

另請注意，當 Webhook URL 接收 POST 通知時，用戶端 ID 的行為應相同。

準備使用

驗證過該行為後，Webhook URL 將按照 Acrobat Sign 標準運作。您可以根據您的需求，進一步更新自訂邏輯。

取得函式 URL

按一下「取得函式 URL」

複製 URL，並使用它在 Acrobat Sign 中建立 Webhook。

建立 AWS Lambda 函式

如要建立 AWS Lambda 函式，請登入 AWS 管理主控台，並從服務清單中選取 AWS Lambda 服務。

按一下「使用「從頭編寫」」建立 Lambda 函式」選項
在「設定函式」頁面中，輸入函式名稱「lambdaWebhook」，並選取 Node.js 4.3 作為執行階段
將「角色」選為現有角色，或從範本建立新角色
- 如果您選擇「從範本建立新角色」，請輸入角色名稱 (例如 role-lamda)，並從「原則範本」清單選取「簡單微服務權限」
按一下「建立函式」按鈕

在新的 AWS lamda 函式頁面上，選取「以內嵌方式編輯程式碼」作為「程式碼輸入類型」，將 index.handler 保留為「處理常式」。
新增邏輯以註冊 Acrobat Sign Webhook
在成功註冊 Webhook 之前，Acrobat Sign 會驗證註冊請求中提供的 Webhook URL 是否確實有意接收通知。為此，當 Acrobat Sign 接收到新的 Webhook 註冊請求時，首先會對 Webhook URL 發出驗證請求。此驗證請求是使用自訂 HTTP 標頭 X-AdobeSign-ClientId 發送到 Webhook URL 的 HTTPS GET 請求。此標頭中的值，應設定為請求建立/註冊 Webhook 的應用程式之用戶端 ID。為了成功註冊 Webhook，Webhook URL 必須以 2XX 回應代碼回應此驗證請求，「而且」還必須以下列兩種方法的其中一種傳回相同的用戶端 ID 值：另請注意，當Webhook URL接收POST通知時，客戶端ID的行為應相同。

按以下兩種情況的其中一種操作：

情況 1：在 X-AdobeSign-ClientId 中傳遞用戶端 ID 作為回應標頭
- 在回應標頭中傳遞 X-AdobeSign-ClientId。這就是於請求中傳遞，且必須在回應中傳回的同一個標頭。
  
  程式碼片段
  在 index.js 檔案中，將自動生成的程式碼片段替換為以下程式碼：

擷取用戶端 ID 的節點 JS 程式碼範例，先驗證，然後在回應標頭中將之傳回
exports.handler = function index(event, context, callback) { // Fetch client id var clientid = event.headers['X-AdobeSign-ClientId']; //Validate it if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } }

擷取用戶端 ID 的節點 JS 程式碼範例，先驗證，然後在回應標頭中將之傳回

exports.handler = function index(event, context, callback) {

// Fetch client id

var clientid = event.headers['X-AdobeSign-ClientId'];

//Validate it

if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

var response = {

statusCode: 200,

headers: {

"X-AdobeSign-ClientId": clientid

}

};

callback(null,response);

}

else {

callback("Oops!! illegitimate call");

}

情況 2：使用 xAdobeSignClientId 金鑰，在回應內文中傳遞用戶端 ID

在 JSON 回應內文中，其中含有 xAdobeSignClientId 金鑰，且其值與在請求標頭中傳送的用戶端 ID 相同。

程式碼片段

以下列程式碼取代 Index.js 檔案：

擷取用戶端 ID 的節點 JS 程式碼範例，先驗證，然後在回應標頭中將之傳回
exports.handler = function index(event, context, callback) { // Fetch client id var clientid = event.headers['X-AdobeSign-ClientId']; //Validate it if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created { var responseBody = { xAdobeSignClientId : clientid }; var response = { statusCode: 200, body: JSON.stringify(responseBody) }; callback(null,response); } else { callback("Opps!! illegitimate call"); } }

擷取用戶端 ID 的節點 JS 程式碼範例，先驗證，然後在回應標頭中將之傳回

exports.handler = function index(event, context, callback) {

// Fetch client id

var clientid = event.headers['X-AdobeSign-ClientId'];

//Validate it

if (clientid =="BGBQIIE7H253K6") //Replace 'BGBQIIE7H253K6' with the client id of the application using which the webhook is created

{

var responseBody = {

xAdobeSignClientId : clientid

};

var response = {

statusCode: 200,

body: JSON.stringify(responseBody)

};

callback(null,response);

}

else {

callback("Opps!! illegitimate call");

}

儲存函式。Lambda 函式已建立，我們即將準備好將其用於即時 Webhook。

設定 AWS API 閘道

如要讓此 Lambda 可透過 HTTP 方法公開存取，我們需要使用我們建立其上的函式設定 AWS API 閘道，作為 API 的後端。

在 AWS 管理主控台中，從「AWS 服務」選取「API 閘道」，然後按一下「建立 API」按鈕

在「建立新 API」頁面選取「新 API」，並輸入「Webhook」作為「API 名稱」。
按一下「建立 API」按鈕
選取「動作」下拉式清單，然後選取「建立資源」選項
勾選「設定為代理資源」項目，然後輸入 validate 作為「資源名稱」，並在「資源路徑」輸入 {proxy+}
讓「啟用 API 閘道 CORS」選項保持未勾選狀態，然後按一下「建立資源」按鈕
保持選取「Lambda 函式代理」作為「整合類型」，並在「Lambda 區域」下拉式清單中選取您建立 Lambda 函式的區域 (可能是您建立 API 閘道的同一區域)。
輸入 validate 作為 Lambda 函式，然後按一下「儲存」按鈕
在「為 Lambda 函式新增權限」快顯視窗中選取「確定」

如果成功執行了上述所有步驟，您將看到以下內容：

部署 API

下一步驟是部署此 API，使其可以使用。

在「動作」下拉式清單選取「部署 API」
於「部署階段」選取「[新階段]」，然後將 prod (或任何您想用來識別此階段的文字) 輸入至「階段名稱」
按一下「部署」按鈕

API 現在已可使用，您可在藍色方塊中找到叫用 URL，如下所示：

請記下此 URL，因為您需要將其輸入為即時 Webhook URL。

準備使用

完成了！將上述URL與「/{nodeJSfunctionName}」一起作為webhook API請求POST中的webhook URL附加。驗證過該行為後，Webhook URL 將按照
Acrobat Sign 標準運作。您可以根據需求進一步更新/新增自訂邏輯。

設定選項

設定 Webhook 需要定義五個元素：

名稱 - 讓其他管理員能夠快速瞭解其意思的直覺式名稱。
範圍 - Webhook 擷取的範圍有多大? 介面中有「帳戶」與「群組」。
- API 支援「帳戶」、「群組」、「使用者」與「資源」範圍。
- 只能為每個 Webhook 定義一個範圍。
URL - Adobe Sign 將 JSON 裝載推往的目標 URL。
事件 - 造成 Adobe Sign 建置 JSON，並將其推送至該 URL 的觸發時機。
- 每個事件都會建置與觸發事件相關的不同裝載。
- 多個事件可包含在單一 Webhook 中。
通知參數 - 通知參數可識別事件 JSON 裝載的區段，允許您僅選取對此 Webhook 來說重要的事件區段 (以減少不必要的資料傳送至 URL)。

在完整定義 Webhook 後，按一下「儲存」，新的 Webhook 便會立刻開始對觸發事件做出反應。

註解：

請設定 Webhook URL，以按照上文說明的驗證通訊協定來回應 Webhook 驗證與 Webhook 通知請求。會發送至從 Acrobat Sign 網路應用程式建立的 Webhook 的用戶端 ID (應用程式 ID) 將為 - UB7E5BXCXY

範圍

帳戶：帳戶中發生的所有已訂閱事件都會觸發推送。
- 帳戶管理員有權查看所有為該帳戶和該帳戶中所有群組定義的 Webhook。
群組：該群組中發生的所有已訂閱事件都會觸發推送。注意：群組範圍的 Webhook 僅為該群組存在。
- 群組管理員只能看到專屬於其群組的 Webhook。他們無法看到帳戶層級的 Webhook，或綁定至其他群組的 Webhook。
- 啟用「使用者加入多個群組」的帳戶，將看到設定套用範圍的群組選項。
使用者帳戶：使用者帳戶的所有已訂閱事件都會觸發推送。使用者層級的 Webhook 只能透過 API 建立。
資源層級 Webhook：將為特定資源建立此項。特定於此資源的事件將推送至 Webhook URL。資源層級的 Webhook 只能透過 API 建立。

URL

Webhook URL 是一種伺服器，會偵聽在事件發生時觸發的傳入 HTTPS POST 通知訊息。

您需要此 URL，讓 Webhook 訂閱事件。

用戶端必須包含 Acrobat Sign 可以 POST 到的 HTTPS URL。此 URL 必須在網際網路上公開可用。
- 例如，127.0.0.1 和 localhost URI 都無法運作。
- URL 端點必須偵聽連接埠 443 或 8443 (由客戶在定義回呼 URL 時決定)。
確保 Webhook 支援傳入事件通知的 POST 請求，和驗證請求的 GET 請求。
防火牆不應封鎖該 URL。

事件

以下是可觸發推送至 Webhook URL 的事件，按物件分組，並依照 UI 中的順序列出。

左側的值是您在 Acrobat Sign UI 中將看到的值。右側的值是 API 中的 Webhook 名稱。

如需有關 Webhook 及其裝載的完整詳細資料，請參閱 Acrobat Sign 開發人員指南。

合約：

UI 元素	Webhook 名稱
合約的所有事件	AGREEMENT_ALL
已建立合約	AGREEMENT_CREATED
已傳送合約	AGREEMENT_ACTION_REQUESTED
合約參與者已完成	AGREEMENT_ACTION_COMPLETED
合約工作流程已完成	AGREEMENT_WORKFLOW_COMPLETED
合約已過期	AGREEMENT_EXPIRED
已刪除合約	AGREEMENT_DOCUMENTS_DELETED
已取消合約	AGREEMENT_RECALLED
已拒絕合約	AGREEMENT_REJECTED
已共用合約	AGREEMENT_SHARED
已委派合約	AGREEMENT_ACTION_DELEGATED
已更換合約參與者	AGREEMENT_ACTION_REPLACED_SIGNER
已修改合約	AGREEMENT_MODIFIED
已認可合約修改	AGREEMENT_USER_ACK_AGREEMENT_MODIFIED
已檢視合約電子郵件	AGREEMENT_EMAIL_VIEWED
已退回合約電子郵件	AGREEMENT_EMAIL_BOUNCED
合約建立失敗	AGREEMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
合約已同步發佈離線事件	AGREEMENT_OFFLINE_SYNC
傳送者已上傳合約	AGREEMENT_UPLOADED_BY_SENDER
已保存合約	AGREEMENT_VAULTED
合約參與者的社會身分已驗證	AGREEMENT_WEB_IDENTITY_AUTHENTICATED
合約參與者已完成 KBA 驗證	AGREEMENT_KBA_AUTHENTICATED
合約提醒已傳送	AGREEMENT_REMINDER_SENT
合約簽署者名稱已由簽署者變更	AGREEMENT_SIGNER_NAME_CHANGED_BY_SIGNER

合約 Webhook 僅透過 API 提供
NA	AGREEMENT_EXPIRATION_UPDATED
NA	AGREEMENT_READY_TO_NOTARIZE
NA	AGREEMENT_READY_TO_VAULT

大量傳送：

UI 元素	Webhook 名稱
「大量傳送」所有事件	MEGASIGN_ALL
已建立「大量傳送」	MEGASIGN_CREATED
已共用「大量傳送」	MEGASIGN_SHARED
已召回「大量傳送」	MEGASIGN_RECALLED

網頁表單：

UI 元素	Webhook 名稱
網頁表單所有事件	WIDGET_ALL
已建立網頁表單	WIDGET_CREATED
已啟用網頁表單	WIDGET_ENABLED
已停用網頁表單	WIDGET_DISABLED
已修改網頁表單	WIDGET_MODIFIED
已共用網頁表單	WIDGET_SHARED
網頁表單建立失敗	WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM

資料庫範本 (僅 API)：

UI 元素	Webhook 名稱
NA	LIBRARY_DOCUMENT_ALL
NA	LIBRARY_DOCUMENT_CREATED
NA	LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
NA	LIBRARY_DOCUMENT_MODIFIED

通知參數

通知參數允許您將 JSON 裝載自訂為僅針對事件的特定元素。

例如，在「已更換合約參與者」事件中，您可能只想要取得「合約資訊」與「參與者資訊」，但想忽略「文件資訊」，藉此減少傳送至 Webhook URL 的 JSON 總計大小。

合約
- 合約資訊 - 根據觸發事件時的合約狀態提供的詳細合約資訊。
- 合約文件資訊 - 包括因事件而生成的所有文件資訊。
- 合約參與者資訊 - 包括因事件而產生的所有參與者資訊。
- 合約已簽署文件 - 提供已簽署的 PDF。
  - 適用於已完成合約工作流程事件和所有事件的合約。
大量傳送
- 大量傳送資訊 - 有關觸發事件的「大量傳送」物件的詳細資訊。
網頁表單
- Widget 資訊 - 有關觸發事件的網頁表單的詳細資訊。
- Widget 文件資訊 - 與網頁表單有關的文件資訊。
- Widget 參與者資訊 - 有關網頁表單中已定義的參與者的資訊。

雙向 SSL 驗證

雙向 SSL (通常稱為用戶端 SSL 或相互 TLS)，是一種 SSL 模式，其中伺服器和用戶端 (網頁瀏覽器) 都提供憑證來識別自己。

帳戶管理員可以在「安全性設定」頁面設定用戶端憑證。

Acrobat Sign 會在將裝載傳送至 Webhook URL 時驗證 SSL 憑證。未通過 SSL 憑證驗證的 Webhook 將無法成功傳遞 JSON 裝載。

使用雙向 SSL 驗證用戶端 (Acrobat Sign) 並偵聽服務，以確保只有 Acrobat Sign 才能訪問您的 Webhook URL。

如果 Webhook 是由合作夥伴應用程式建立，則在傳送 Webhook 通知時，Webhook 將使用合作夥伴應用程式帳戶中的用戶端憑證 (如果可用) 來識別自己。

進一步瞭解 SSL/TSL 需求。

以下是網頁伺服器驗證程序和用戶端認證驗證的最常見問題。

網頁伺服器驗證

在註冊 Webhook 期間，Acrobat Sign 會驗證 Webhook 伺服器 URL。

如果無法從 Acrobat Sign 完成與 Webhook 回呼 URL 的連線，客戶將無法註冊 Webhook。

否。

Webhook 回呼 URL 僅能為連接埠 443 或 8443 的 HTTPS。

Acrobat Sign 會封鎖傳出至所有其他連接埠的 HTTPS 流量。

若要驗證伺服器憑證，使用 DigiCert®SSL 安裝診斷工具是好方法。

僅輸入主機名稱，例如：www.digicert.com

常見問題包括：

問題：使用不受信任的 CA 或自我簽署憑證

修正：針對 Webhook 回呼伺服器使用公開 CA 所核發的 SSL 憑證。

問題：伺服器未傳送中繼憑證

修正：在 Webhook 回呼伺服器上安裝中繼憑證。

請造訪 https://www.digicert.com/kb/ssl-certificate-installation.htm 以取得詳細資訊。

用戶端憑證驗證

為了為 Webhook 設定雙向 SSL，管理員需要上傳內含私人金鑰的 .p12 (或 .pfx) 檔案。檔案會安全地儲存在客戶帳戶中，管理員可以完全控制，以隨時移除檔案。

在雙向 Webhook 設定中，Acrobat Sign 為來電者/用戶端，需要私人金鑰以證明是由 Acrobat 代表客戶帳戶進行通話。

確認雙向 SSL 已啟用

在 Webhook 回呼伺服器上必須啟用雙向 SSL。

使用任何網頁瀏覽器連線至 Webhook 回呼 URL。您應該會看到：
```
400 Bad Request
No required SSL certificate sent
(400 錯誤請求
未傳送必要的 SSL 憑證)
```
這表示伺服器預期用戶端會傳送用戶端憑證 (即伺服器已啟用雙向 SSL)。

如果您沒有看到上述訊息，表示並未啟用雙向 SSL。

註解：

您可以使用 Postman，並對 Webhook 回呼 URL 執行 POST 請求。您應該會看到類似的結果。

在本機驗證用戶端憑證

用戶端憑證可以是自我簽署憑證或 CA 發行的憑證。但是必須至少符合下列 X.509 v3 擴充功能：

X.509 v3 擴充功能	值
ExtendedKeyUsage	clientAuth (OID：1.3.6.1.5.5.7.3.2)
KeyUsage	digitalSignature

用戶端憑證必須是副檔名為 .p12 或 .pfx 的 PKCS12 檔案，且必須同時包含用戶端憑證 (以便伺服器可驗證用戶端身分) 及用戶端的私人金鑰 (讓用戶端能夠數位簽署伺服器訊息以在 SSL 交握期間驗證)。

使用 openssl 命令來驗證 p12 (pfx) 檔案：

openssl pkcs12 -info -in outfile.p12

應請求提供私人金鑰的密碼片語。輸出應包含這兩種憑證，以及一個加密的私人金鑰，例如：

Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
subject=/C=US/ST=California/L=San Jose/O=Adobe Inc./CN=sp.adobesignpreview.com
issuer=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
-----BEGIN CERTIFICATE-----
MIIGwDCCBaigAwIBAgIQAhJSKDdyQZjlbYO5MJAYOTANBgkqhkiG9w0BAQsFADBP
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMSkwJwYDVQQDEyBE
...
JAKQLQ==
-----END CERTIFICATE-----
Bag Attributes: <No Attributes>
subject=/C=US/O=DigiCert Inc/CN=DigiCert TLS RSA SHA256 2020 CA1
issuer=/C=US/O=DigiCert Inc/OU=www.digicert.com/CN=DigiCert Global Root CA
-----BEGIN CERTIFICATE-----
MIIEvjCCA6agAwIBAgIQBtjZBNVYQ0b2ii+nVCJ+xDANBgkqhkiG9w0BAQsFADBh
MQswCQYDVQQGEwJVUzEVMBMGA1UEChMMRGlnaUNlcnQgSW5jMRkwFwYDVQQLExB3
...
-----END CERTIFICATE-----
Bag Attributes
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
Key Attributes: <No Attributes>
-----BEGIN ENCRYPTED PRIVATE KEY-----
MIIFDjBABgkqhkiG9w0BBQ0wMzAbBgkqhkiG9w0BBQwwDgQI7eNh2qlsLPkCAggA
...
FHE=
-----END ENCRYPTED PRIVATE KEY-----

憑證應至少包含終端實體憑證和中繼憑證。理想情況下，也會包含根 CA 憑證。

通知:

確認 .p12 或 .pfx 檔案有密碼片語保護。

建立自我簽署用戶端憑證 (選用)

視您的需求而定，用戶端憑證可以是由 CA 簽發或自我簽署。

若要產生自我簽署用戶端憑證，請使用下列 openssl 命令：

openssl req -newkey rsa:4096 -keyform PEM -keyout ca.key -x509 -days 3650 -outform PEM -out ca.cer

注意：

將產生的檔案保持機密，因為它們是您自我簽署的 CA 憑證。
接下來，產生用戶端 .p12 檔案：
1. 為 SSL 用戶端產生私人金鑰：
  openssl genrsa -out client.key 2048
2. 使用用戶端私人金鑰來產生憑證請求：
  openssl req -new -key client.key -out client.req
3. 使用憑證請求和 CA 憑證/金鑰核發用戶端憑證：
  openssl x509 -req -in client.req -CA ca.cer -CAkey ca.key -set_serial 101 -extensions client -days 365 -outform PEM -out client.cer
4. 將用戶端憑證和私人金鑰轉換為 pkcs#12 格式以供瀏覽器使用：
  openssl pkcs12 -export -inkey client.key -in client.cer -out client.p12
5. 移除用戶端私人金鑰、用戶端憑證和用戶端請求檔案，因為 pkcs12 具備您所需的一切。
  rm client.key client.cer client.req
根據遠端伺服器驗證用戶端憑證
- 使用 Postman 在「設定 > 憑證」中載入用戶端 PFX 檔案。
- 選取「新增憑證」以新增用戶端憑證。
- 設定 x-adobesign-clientid 的 HTTP 標頭：
設定完成後，將 POST 請求傳送至 Webhook 回呼 URL。

您應該會得到 200 個回應。
為什麼即使已使用 Postman 驗證過 PFX 檔案，Acrobat Sign 還是拒絕我的 PFX 檔案?

如果您遵循以上程序進行 pfx 檔案驗證，且 Acrobat Sign 仍拒絕 pfx 檔案，則檔案可能是由能夠產生非標準 PKCS12 檔案的 Microsoft 工具所產生。

在這種情況下，請使用下列 openssl 命令從 pfx 檔案解壓縮憑證及私人金鑰，然後產生正確格式的 PKCS12 檔案：
```
// Extract certificates and private key from pfx file
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.crt -nokeys
openssl pkcs12 -info -in microsoftclientssl.pfx -passin pass:&quot;&quot; -out clientcert.key -nodes -nocerts

// Create new PKCS12 file
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
```

如何啟用或停用

企業方案帳戶預設啟用對 Webhook 功能的存取權。

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

如要訪問 Webhook 頁面，可至「管理」選單的左側邊欄：「帳戶 > Webhooks」

啟用 Webhook

首次建立 Webhook 時，會建立為「作用中」狀態。

在 Acrobat Sign 的 Webhook 頁面上，預設將顯示「作用中」的 Webhook。

如要啟用非作用中的 Webhook，請執行以下操作：

按一下 Webhook 標題列右側的「選項」圖示 (三條水平線)，並選取「顯示所有 Webhook」

按一下非作用中的 Webhook 以選取
- 這將在標題列下顯示 Webhook 的選項
按一下「啟用」

觸發下一個事件後，作用中的 Webhook 便會立即開始向目標 URL 發送資料。

停用 Webhook

若要停用 Webhook，您只需

瀏覽至「Webhook」頁面
按一下您要停用的 Webhook
從標題列下方的選單項目中選取「停用」
- 停用後，該 Webhook 將顯示為「非作用中」狀態

檢視或編輯 Webhook

您可隨時編輯並儲存 Webhook，而在儲存新設定後，變更將立即生效。

只能編輯「事件」和「通知參數」。

如需變更「名稱」、「範圍」或「URL」，就必須建立新的 Webhook。

如要編輯 Webhook 的參數：

瀏覽至「Webhook」頁面
按一下您要編輯的 Webhook
按一下標題列下方的「檢視/編輯」選項

套用所需的任何變更後，按一下「儲存」

刪除 Webhook

您可隨時刪除 Webhook。

刪除 Webhook 會將其在系統中銷毀，因此您無法恢復已刪除的 Webhook。

您不需要先停用 Webhook。

如要刪除 Webhook：

瀏覽至「Webhook」
按一下您要刪除的 Webhook，即可加以選取
按一下標題列下方的「刪除」選項
畫面會出現提示，以確定您真的想刪除 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 通知

若有針對該使用者、其群組或其帳戶設置了 Webhook，則 Acrobat Sign Webhook 會傳遞適用於所有合約參與者的通知。

處理合約事件的方式是，如果有為該事件的適用參與者設置了 Webhook，系統便會向該 Webhook URL 發送通知。換句話說，所有適用合約中的事件都會觸發 Webhook，即使是在設置了 Webhook 的群組或帳戶之外的那些事件仍是一樣。

系統只會針對那些參與者有參與的事件發送通知。例如，合約的「傳送者」會收到幾乎所有的通知，而「收件者」則僅從他們參與合約的一開始收到通知，且僅限於與他們有關的那些事件。

Webhook 通知遵循 Acrobat Sign 本身目前的驗證與可見度模型，這意味著只有當使用者開始參與合約時，才能存取合約。

「傳送者」向三個簽署者發送合約以進行簽署。

該傳送者帳戶中設定了帳戶層級的「WebhookX」。
簽署者 1 是與傳送者同帳戶的成員，但位於其他群組中，且該群組設定了「WehbhookY」。
簽署者 2 是不同帳戶的成員，且該「簽署者 2」帳戶中設定了帳戶層級的「WebhookZ」。
簽署者 3 是與傳送者同帳戶的成員。

傳送者發送合約：「WebhookX」觸發「建立合約」與「發送合約」，而「WebhookY」觸發「發送合約」。

簽署者 1 簽署：「WebhookX」觸發「合約參與者已完成」和「發送合約」，「WebhookY」觸發「合約參與者已完成」，而「WebhookZ」觸發「發送合約」。

簽署者 2 簽署：「WebhookX」觸發「合約參與者已完成」和「發送合約」，而「WebhookZ」則發送「合約參與者已完成」的通知。

簽署者 3 簽署：「WebhookX」觸發「合約參與者已完成」和「已完成合約工作流程」，「WebhookY」觸發「已完成合約工作流程」，而「WebhookZ」觸發「已完成合約工作流程」。

當偵聽服務關閉時重試

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

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

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

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

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

更快、更輕鬆地獲得協助

新的使用者？

設定 Webhook

概覽

使用方式

驗證 Webhook URL 的目的

如何回應 Webhook 通知

1. HTTP 標頭 X-AdobeSign-ClientId 和作為此用戶端 ID 的值

2. 具有金鑰為 xAdobeSignClientId，且值為同一用戶端 ID 的 JSON 回應內文

必要條件

建立做為 Acrobat Sign Webhook 的 Azure 函式觸發程式的步驟

新增邏輯以註冊 Acrobat Sign Webhook

選項 1：在 X-AdobeSign-ClientId 中傳遞用戶端 ID 作為回應標頭

選項 2：使用 xAdobeSignClientId 金鑰在回應內文中傳遞用戶端 ID

準備使用

建立 AWS Lambda 函式

情況 1：在 X-AdobeSign-ClientId 中傳遞用戶端 ID 作為回應標頭

情況 2：使用 xAdobeSignClientId 金鑰，在回應內文中傳遞用戶端 ID

設定 AWS API 閘道

部署 API

準備使用

設定選項

範圍

URL

事件

合約：

大量傳送：

網頁表單：

資料庫範本 (僅 API)：

通知參數

雙向 SSL 驗證

網頁伺服器驗證

用戶端憑證驗證

如何啟用或停用

啟用 Webhook

停用 Webhook

檢視或編輯 Webhook

刪除 Webhook

最佳實務

注意事項…

JSON 大小限制

Webhook 通知

當偵聽服務關閉時重試

更快、更輕鬆地獲得協助