用户指南取消(C)

配置 Webhook

搜索

上次更新日期： 2024年1月10日 | 也应用至 Adobe Acrobat Sign

Adobe Sign

打开应用程序

Adobe Acrobat Sign 集成
新增功能
产品版本和生命周期
Acrobat Sign for Salesforce
Acrobat Sign for Microsoft
1. Acrobat Sign for Microsoft 365
  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
Acrobat Sign for ServiceNow
适用于 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. 安装指南
Acrobat Sign for Zapier
Acrobat Sign 开发人员文档

概述

Webhook 是用户定义的 HTTPS 请求，在源站点发生订阅事件时触发（本例中为 Adobe Acrobat Sign）。

实际上，Webhook 只是一种接受数据或数据流的 REST 服务。

Webhook 适用于 PUSH 模型中的服务到服务通信。

当触发订阅事件时，Acrobat Sign 会构造包含 JSON 正文的 HTTPS POST，并将其传递至指定的 URL。

相较于以往的回调方法，Webhook 有多方面的好处，其中包括：

管理员可以启用自己的 Webhook 来列出回调 URL，而无需请 Acrobat Sign 支持参与
Webhook 在数据“新鲜度”、通信效率和安全性方面更佳。无需轮询
Webhook 能轻松支持不同级别的范围（帐户/组/用户/资源）。
Webhook 是一种更现代的 API 解决方案，以更简单的方式配置现代应用程序
每个范围（帐户/组/用户/资源）可配置多个 Webhook，其中回调必须是唯一的
Webhook 允许选择要返回的数据，其中回调是“全有或全无”式解决方案
可以配置使用 Webhook 传输的元数据（基本或详细）
由于 UI 完全受管理员的控制，因此根据需要创建、编辑或禁用 Webhook 容易得多。

注意:

此文档主要关注 Acrobat Sign Web 应用程序（先前为 Adobe Sign）中的 Webhook UI。

想要了解 API 详细信息的开发人员可通过以下网址找到更多信息：

REST v6 详细信息

使用方式

管理员首先需要拥有 Webhook 服务，准备好接受来自 Acrobat Sign 的入站推送。在这方面有很多选择，只要服务可以接受 POST 和 GET 请求，Webhook 就能成功。

具备服务后，Acrobat Sign 管理员可以从 Acrobat Sign 站点“帐户”菜单中的 Webhook 界面创建新 Webhook。

管理员可以配置 Webhook，以触发协议、Web 表单（构件）或批量发送 (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 的 HTTPS GET 请求。此请求具有自定义 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：INACTIVE 更新为 ACTIVE：如果此 Webhook URL 调用验证失败，Webhook 状态将无法更改为 ACTIVE。

如何响应 Webhook 通知

Acrobat Sign 在已发送至 Webhook URL 的每个 Webhook 通知请求中执行意图的隐式验证。因此，每个 Webhook 通知 HTTPS 请求还包括称为 X-AdobeSign-ClientId 的自定义 HTTP 标头。此标头的值是创建 Webhook 的应用程序的客户端 ID（应用程序 ID）。当且仅当返回成功响应（2XX 响应代码）且在 HTTP 标头 (X-AdobeSign-ClientId) 或 JSON 响应正文发送客户端 ID 时（使用响应正文方法时，键为 xAdobeSignClientId，值为相同的客户端 ID），我们才会认为成功传递 Webhook 通知，否则我们将重试向 Webhook URL 传递通知，直至重试次数用尽。

如上所述，签名的每个通知请求中包括标头 'X-AdobeSign-ClientId'，此标头的值（客户端 ID）应通过以下两种方式之一在响应中回显：

1. HTTP 标头 X-AdobeSign-ClientId 且值为此客户端 ID

示例 Javascript 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应标头中
//获取客户端 ID var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //对其进行验证 if (clientid ==="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID { //将其返回到响应标头中 response.headers['X-AdobeSign-ClientId'] = clientid; response.status = 200; //默认值 }

示例 PHP 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应标头中
<?php //获取客户端 ID $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //对其进行验证 if ($clientid == "BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID { //将其返回到响应标头中 header("X-AdobeSign-ClientId:$clientid"); header("HTTP/1.1 200 OK"); // 默认值 } ?>

2. JSON 响应正文，键为 xAdobeSignClientId，值为相同的客户端 ID

示例 Javascript 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应正文中
//获取客户端 ID var clientid = request.headers['X-ADOBESIGN-CLIENTID']; //对其进行验证 if (clientid ==="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID { var responseBody = { "xAdobeSignClientId" : clientid //在正文中返回客户端 ID }; response.headers['Content-Type'] = 'application/json'; response.body = responseBody; response.status = 200; }

示例 Javascript 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应正文中

//获取客户端 ID

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

//对其进行验证

if (clientid ==="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID

{

var responseBody = {

"xAdobeSignClientId" : clientid //在正文中返回客户端 ID

};

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

response.body = responseBody;

response.status = 200;

}

示例 PHP 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应正文中
<?php //获取客户端 ID $clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID']; //对其进行验证 if ($clientid == "BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID { //将其返回到响应正文中 header("Content-Type: application/json"); $body = array('xAdobeSignClientId' => $clientid); echo json_encode($body); header("HTTP/1.1 200 OK"); // 默认值 } ?>

示例 PHP 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应正文中

<?php

//获取客户端 ID

$clientid = $_SERVER['HTTP_X_ADOBESIGN_CLIENTID'];

//对其进行验证

if ($clientid == "BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID

{

//将其返回到响应正文中

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

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

echo json_encode($body);

header("HTTP/1.1 200 OK"); // 默认值

}

示例响应 JSON 正文
{ "xAdobeSignClientId": "BGBQIIE7H253K6" }

先决条件

您将需要：

具有许可证的 Microsoft 帐户，用于创建 Azure Function 应用程序
现有 Azure Functions 应用程序，您可以使用 https://docs.microsoft.com/zh-cn/azure/azure-functions/functions-create-first-azure-function 创建一个
Javascript 基本知识，以便您理解代码，并使用自选的任何语言编写代码

创建 Azure Functions 触发器（用作 Acrobat Sign Webhook）的步骤

要创建 Javascript HTTP 触发器函数，请执行以下操作：

1. 通过您的 Microsoft 帐户登录 https://portal.azure.com/

2. 打开显示在“函数应用”选项卡下方的 Azure Functions 应用程序。

这将打开 Azure Function 应用程序列表：

3. 选择您想要在其中创建此新函数的应用程序

4. 单击“创建”(+) 按钮以创建新 Azure 函数

5. 选择 Webhook + API 作为场景，选择 Javascript 作为语言

6. 单击创建此函数

将创建具有处理传入 API 请求功能的新函数。

添加逻辑以注册 Acrobat Sign Webhook

在成功注册 Webhook 之前，Acrobat Sign 会验证注册请求中提供的 Webhook URL 是否真正旨在接收通知。出于此目的，当通过 Acrobat Sign 接收新 Webhook 注册请求时，它将首先向 Webhook URL 发出验证请求。此验证请求是发送至 Webhook URL 的 HTTPS GET 请求（具有自定义 HTTP 标头 X-AdobeSign-ClientId）。此标头中的值将设置为请求创建/注册 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'];

//验证传入客户端 ID 是否属实

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

context.res = {

// 状态：200，/* 默认为 200 */ // 可接受任何 2XX 响应

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'];

//验证传入客户端 ID 是否属实

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

context.res = {

// 状态：200，/* 默认为 200 */ // 可接受任何 2XX 响应

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 通知时，clientID 预期出现相同行为。

准备使用

当您验证行为后，Webhook URL 将按照 Acrobat Sign 标准工作。您可以根据您的需求进一步更新自定义逻辑。

获取函数 URL

单击获取函数 URL

复制 URL 并将其用于在 Acrobat Sign 中创建 webhook。

创建 AWS Lambda 函数

要创建 AWS Lambda，请登录您的 AWS 管理控制台，然后从服务列表中选择 AWS Lambda 服务。

单击使用“从头开始创作”创建 Lambda 函数选项
在“配置函数”页面中，输入函数名称 "lambdaWebhooks"，然后选择 Node.js 4.3 作为运行时
对于角色，请选择一个现有角色或从模板创建一个新角色。
- 如果您选择了从模板创建新角色，请输入角色名称（例如，role-lamda），然后从策略模板列表中选择简单微服务权限。
单击创建函数按钮

在新 AWS lamda 函数页面上，选择“编辑代码内联”作为“代码输入类型”，继续将 index.handler 用作处理程序。
添加逻辑以注册 Acrobat Sign Webhook
在成功注册 Webhook 之前，Acrobat Sign 会验证注册请求中提供的 Webhook URL 是否真正旨在接收通知。出于此目的，当通过 Acrobat Sign 接收新 Webhook 注册请求时，它将首先向 Webhook URL 发出验证请求。此验证请求是发送至 Webhook URL 的 HTTPS GET 请求（具有自定义 HTTP 标头 X-AdobeSign-ClientId）。此标头中的值将设置为请求创建/注册 Webhook 的应用程序的客户端 ID。为成功注册 Webhook，Webhook URL 必须通过 2XX 响应代码响应此验证请求，而且，它还必须通过以下两种方式之一发回相同的客户端 ID 值。 Also note the same behavior for clientID is expected when the Webhook URL receives POST notifications.

遵循以下两种情况之一：

情况 1：在作为响应标头的 X-AdobeSign-ClientId 中传递客户端 ID
- 在响应标头中传递 X-AdobeSign-ClientId。它是在请求中传递的同一标头，并且必须在响应中回显。
  
  代码片段
  在 index.js 文件中，将自动生成的代码片段替换为以下代码：

示例节点 JS 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应标头中
exports.handler = function index(event, context, callback) { //获取客户端 ID var clientid = event.headers['X-AdobeSign-ClientId']; //对其进行验证 if (clientid =="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID { var response = { statusCode: 200, headers: { "X-AdobeSign-ClientId": clientid } }; callback(null,response); } else { callback("Oops!! illegitimate call"); } }

示例节点 JS 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应标头中

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

//获取客户端 ID

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

//对其进行验证

if (clientid =="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID

{

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 文件替换为以下项：

示例节点 JS 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应标头中
exports.handler = function index(event, context, callback) { //获取客户端 ID var clientid = event.headers['X-AdobeSign-ClientId']; //对其进行验证 if (clientid =="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID { var responseBody = { xAdobeSignClientId : clientid }; var response = { statusCode: 200, body: JSON.stringify(responseBody) }; callback(null,response); } else { callback("Opps!! illegitimate call"); } }

示例节点 JS 代码，用于获取客户端 ID、对其进行验证，然后将其返回到响应标头中

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

//获取客户端 ID

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

//对其进行验证

if (clientid =="BGBQIIE7H253K6") //将 'BGBQIIE7H253K6' 替换为创建 Webhook 时使用的应用程序的客户端 ID

{

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 方法公开访问，我们需要使用我们的函数（上面已创建）作为 API 后端来配置 AWS API 网关。

在 AWS 管理控制台中，从 AWS 服务选择 API 网关，然后单击创建 API 按钮

在创建新 API 页面中，选择新 API，然后输入 webhooks 作为 API 名称。
单击创建 API 按钮
选择操作下拉列表，然后选择创建资源选项
单击配置为代理资源选项，然后在资源名称中输入验证，在资源路径中输入 {proxy+}
将启用 API 网关 CORS 选项保持为取消选中，然后单击创建资源按钮
将 Lambda 函数代理保持选择为集成类型，且在 Lambda 区域下拉列表中选择您已在其中创建 Lambda 函数的区域（可能与您正在创建 API 网关的区域相同）。
在 Lambda 函数中输入验证，然后单击保存按钮
在为 Lambda 函数添加权限弹出窗口中，单击确定

如果上述所有步骤均执行成功，您将看到如下显示：

部署 API

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

在操作下拉列表中，选择部署 API
在部署阶段中选择[新阶段]，然后在阶段名称中输入生产（或您想要识别此阶段的任何内容）
单击部署按钮

API 现在可供使用，且您可以在蓝框中找到调用 URL，如下所示：

记下此 URL，因为您后续要输入它作为实时 Webhook URL。

准备使用

完成。 Use this above url with "/{nodeJSfunctionName}" appended as webhook url in POST /webhooks API request. 当您验证行为后，Webhook URL 将按照 Acrobat Sign 标准工作。
您可以根据您的需求进一步更新/添加自定义逻辑。

配置选项

配置 Webhook 需要定义五个元素：

名称 - 建议使用其他管理员可轻松理解的直观名称。
范围 - Webhook 捕捉的网络范围是多少？“帐户”和“组”在界面中可用。
- 此 API 支持“帐户”、“组”、“用户”和“资源”范围。
- 每个 Webhook 只能定义一个范围。
URL - Acrobat Sign 会将 JSON 负载推送到的目标 URL。
事件 - 导致 Acrobat Sign 生成 JSON 并将其推送到 URL 的触发器。
- 每个事件都会生成与触发器事件相关的不同负载。
- 多个事件可包括在一个 Webhook 中。
通知参数 - 通知参数识别事件 JSON 负载部分，从而允许您仅选择对此 Webhook 而言重要的事件部分（因此，可减少发送到 URL 的不必要数据）。

完全定义 Webhook 后，单击保存，然后新的 Webhook 会立即开始响应触发器事件。

注意:

请根据上述验证协议配置您的 Webhook URL，以响应 Webhook 验证和 Webhook 通知请求。将发送至从 Acrobat Sign Web 应用程序创建的 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 提供
不适用	AGREEMENT_EXPIRATION_UPDATED
不适用	AGREEMENT_READY_TO_NOTARIZE
不适用	AGREEMENT_READY_TO_VAULT

批量发送：

UI 元素	Webhook 名称
“批量发送”所有事件	MEGASIGN_ALL
已创建“批量发送”	MEGASIGN_CREATED
已共享“批量发送”	MEGASIGN_SHARED
已召回“批量发送”	MEGASIGN_RECALLED

Web 表单：

UI 元素	Webhook 名称
Web 表单所有事件	WIDGET_ALL
已创建 Web 表单	WIDGET_CREATED
已启用 Web 表单	WIDGET_ENABLED
已禁用 Web 表单	WIDGET_DISABLED
已修改 Web 表单	WIDGET_MODIFIED
已共享 Web 表单	WIDGET_SHARED
Web 表单创建失败	WIDGET_AUTO_CANCELLED_CONVERSION_PROBLEM

库模板（仅限 API）：

UI 元素	Webhook 名称
不适用	LIBRARY_DOCUMENT_ALL
不适用	LIBRARY_DOCUMENT_CREATED
不适用	LIBRARY_DOCUMENT_AUTO_CANCELLED_CONVERSION_PROBLEM
不适用	LIBRARY_DOCUMENT_MODIFIED

通知参数

通知参数允许您仅将 JSON 负载自定义为事件的特定元素。

例如，在已替换协议参与者事件中，您可能仅想要获取协议信息和参与者信息，忽略文档信息，且减小发送到 Webhook URL 的 JSON 总大小。

协议
- 协议信息 - 基于触发事件时协议状态的详细协议信息。
- 协议文档信息- 包括由于事件而生成的任何文档信息。
- 协议参与者信息 - 包括由于事件而生成的任何参与者信息。
- 协议已签署文档 - 提供已签名的 PDF。
  - 适用于已完成协议工作流程和协议所有事件。
批量发送
- 批量发送信息 - 有关触发事件的批量发送对象的详细信息。
Web 表单
- 构件信息 - 有关触发事件的 Web 表单的详细信息。
- 构件文档信息 - 与 Web 表单相关的文档信息。
- 构件参与者信息 - 有关 Web 表单中已定义参与者的信息。

双重 SSL 身份验证

双重 SSL（通常称为客户端 SSL 或相互 TLS）是一种 SSL 模式，其中服务器和客户端（Web 浏览器）出示证书，以识别自身身份。

帐户管理员可以在安全性设置页面上配置客户端证书。

Acrobat Sign 在向 Webhook URL 传递负载时验证 SSL 证书。SSL 证书验证失败的 Webhook 无法成功传递 JSON 负载。

使用双重 SSL 以对客户端 (Acrobat Sign) 进行身份验证，并侦听服务，以确保仅 Acrobat Sign 可访问 Webhook URL。

如果 Webhook 是由合作伙伴应用程序创建的，则在发送 Webhook 通知时，Webhook 将使用来自合作伙伴应用程序帐户的客户端证书（如果可用）来识别自身身份。

了解有关 SSL/TSL 要求的更多信息。

以下是 Web 服务器验证过程和客户端认证验证的最常见问题。

Web 服务器验证

如果无法从 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 Sign 代表客户帐户进行的。

验证是否启用了双向 SSL

必须在 Webhook 回调服务器上启用双向 SSL。

使用任意 Web 浏览器连接到 Webhook 回调 URL。您应当收到：
```
400 错误的请求
未发送所需的 SSL 证书
```
这意味着服务器希望客户端发送客户端证书（即：为服务器启用双向 SSL）。

如果没有看到上述消息，则说明双向 SSL 未启用。

注意:

您可以使用 Postman，并向 Webhook 回调 URL 发出 POST 请求。您应该会得到类似的结果。

本地验证客户端证书

客户端凭据可以是自签名证书，也可以是 CA 颁发的证书。但是，它必须至少符合以下 X.509 v3 扩展：

X.509 v3 扩展	Value
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

应该请求私钥的密码。输出应同时包含证书和加密私钥，例如：

包属性
    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-----
包属性：<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-----
包属性
    localKeyID: 9D BD 22 80 E7 B2 B7 58 9E AE C8 42 71 F0 39 E1 E7 2B 57 DB
关键属性：<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 标头：
配置完成后，向 Webhook 回调 URL 发送 POST 请求。

您应该会得到一个 200 响应。
为何 Acrobat Sign 会拒绝我的 PFX 文件，即使我已经通过 Postman 验证了该文件？

如果您已按照上述流程验证 pfx 文件，但 Acrobat Sign 仍拒绝该 pfx 文件，则该文件可能是由可生成非标准 PKCS12 文件的 Microsoft 工具生成的。

在这种情况下，请使用以下 openssl 命令从 pfx 文件中提取证书和私钥，然后生成格式正确的 PKCS12 文件：
```
// 从 pfx 文件提取证书和私钥
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

// 新建 PKCS12 文件
openssl pkcs12 -export -inkey clientcert.key -in clientcert.crt -out clientcert.pfx
```

如何启用或禁用

默认情况下，对于企业计划帐户，已启用访问 Webhook 功能。

组级别管理员可以创建/控制仅在其组中运行的 Webhook。

可以在管理员菜单的左边栏中找到访问 Webhook 页面：帐户 > Webhook

激活 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

已签名文档将首先被截断，然后是参与者信息、文档信息和最终详细信息。

例如，对于协议完成事件（如果它也包括已签名文档（base 64 编码））或具有多个窗体字段的协议而言，可能会发生此情况。

Webhook 通知

如果有针对用户、其组或帐户配置的 Webhook，则 Acrobat Sign Webhook 传递适用于协议所有参与者的通知。

协议事件以以下方式进行处理：如果有针对该事件适用参与者配置的 Webhook，将向该 Webhook URL 发送通知。换句话说，Webhook 针对所有适用协议中的事件触发，即使它们在配置 Webhook 的组或帐户范围外。

仅针对参与者涉及的事件传递通知。例如，协议发件人接收几乎所有通知，而收件人仅从他们参与协议开始时接收通知，且仅接收他们涉及事件的通知。

Webhook 通知遵循 Acrobat Sign 的当前身份验证和可见性模型，这意味着用户仅在他们开始参与协议时有权访问协议。

发件人向三个签名者发送签名协议。

有一个针对发件人帐户配置的帐户级别 WebhookX。
Signer1 是与发件人相同帐户的成员，但在不同组中，且有针对该组配置的 WehbhookY。
Signer2 是不同帐户的成员，且有针对 Signer2 帐户配置的帐户级别 WebhookZ。
Signer3 是与发件人相同帐户的成员。

发件人发送协议：WebhookX 触发“已创建协议”和“已发送协议”，而 WebhookY 触发“已发送协议”。

Signer1 签名：WebhookX 触发“协议参与者已完成”和“已发送协议”、WebhookY 触发“协议参与者已完成”，且 WebhookZ 触发“已发送协议”。

Signer2 签名：WebhookX 触发“协议参与者已完成”和“已发送协议”，而 WebhookZ 发送“协议参与者已完成”通知。

Signer3 签名：WebhookX 触发“协议参与者已完成”和“已完成协议工作流程”、WebhookY 触发“已完成协议工作流程”且 WebhookZ 触发“已完成协议工作流程”。

侦听服务停止时重试

如果 Webhook 的目标 URL 因任何原因而停止运转，Acrobat 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. JSON 响应正文，键为 xAdobeSignClientId，值为相同的客户端 ID

先决条件

创建 Azure Functions 触发器（用作 Acrobat Sign Webhook）的步骤

添加逻辑以注册 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

事件

协议：

批量发送：

Web 表单：

库模板（仅限 API）：

通知参数

双重 SSL 身份验证

Web 服务器验证

客户端证书验证

如何启用或禁用

激活 Webhook

停用 Webhook

查看或编辑 Webhook

删除 Webhook

最佳实践

注意事项...

JSON 大小限制

Webhook 通知

侦听服务停止时重试

更快、更轻松地获得帮助