示例 Javascript 代码,用于获取客户端 ID、对其进行验证,然后将其返回到响应标头中
新增功能
快速入门
管理
- Admin Console 概述
- 用户管理
- 帐户/组设置
- 监管要求指导
- 申请您的域
- “举报滥用”链接
发送、签署和管理协议
- 收件人选项
- 发送协议
-
在文档中创作字段
- 应用程序内创作环境
- 使用文本标记创建表单
- 使用 Acrobat (AcroForms) 创建表单
- 字段
- 创作常见问题
- 签署协议
- 管理协议
- 审核报告
- 报告和数据导出
高级协议功能和工作流程
- Web 表单
- 可重复使用的模板
- 转让 Web 表单和库模板的所有权
-
Power Automate 工作流程
- Power Automate 集成和包含的权限概述
- 启用 Power Automate 集成
- “管理”页面上的上下文操作
- 跟踪 Power Automate 使用情况
- 创建新的工作流(示例)
- 用于工作流的触发器
- 从 Acrobat Sign 外部导入工作流
- 管理工作流
- 编辑工作流
- 共享工作流
- 禁用或启用工作流
- 删除工作流
-
实用模板
- 仅限管理员
- 协议存档
- Web 表单协议存档
- 协议数据提取
- 协议通知
- 协议生成
- 自定义发送工作流程
- 共享用户和协议
与其他产品集成
- Acrobat Sign for Salesforce
- Acrobat Sign for Microsoft
- 其他集成
- 合作伙伴管理的集成
- 如何获取集成密钥
Acrobat Sign 开发人员
- REST API
支持和故障排除
概述
Webhook 是用户定义的 HTTPS 请求,在源站点发生订阅事件时触发(本例中为 Adobe Acrobat Sign)。
实际上,Webhook 只是一种接受数据或数据流的 REST 服务。
Webhook 适用于 PUSH 模型中的服务到服务通信。
当触发订阅事件时,Acrobat Sign 会构造包含 JSON 正文的 HTTPS POST,并将其传递至指定的 URL。
在配置 Webhook 之前,请确保您的网络接受 Webhook 功能所需的 IP 范围。
相较于以往的回调方法,Webhook 有多方面的好处,其中包括:
- 管理员可以启用自己的 Webhook 来列出回调 URL,而无需请 Acrobat Sign 支持参与
- Webhook 在数据“新鲜度”、通信效率和安全性方面更佳。无需轮询
- Webhook 能轻松支持不同级别的范围(帐户/组/用户/资源)。
- Webhook 是一种更现代的 API 解决方案,以更简单的方式配置现代应用程序
- 每个范围(帐户/组/用户/资源)可配置多个 Webhook,其中回调必须是唯一的
- Webhook 允许选择要返回的数据,其中回调是“全有或全无”式解决方案
- 可以配置使用 Webhook 传输的元数据(基本或详细)
- 由于 UI 完全受管理员的控制,因此根据需要创建、编辑或禁用 Webhook 容易得多。
此文档主要关注 Acrobat Sign Web 应用程序(先前为 Adobe Sign)中的 Webhook UI。
想要了解 API 详细信息的开发人员可通过以下网址找到更多信息:
管理员可以登录到 Adobe Admin Console 以添加用户。登录后,导航至管理员的菜单并向下滚动至 Webhook。
使用方式
管理员首先需要拥有 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 传递通知,直至重试次数用尽。
如何启用或禁用
默认情况下,对于企业级帐户,已启用访问 Webhook 功能。
组级别管理员可以创建/控制仅在其组中运行的 Webhook。
可以在管理员菜单的左边栏中找到访问 Webhook 页面的方法。
基于并发的速率限制
Webhook(和回调)创建和通知事件在从 Acrobat Sign 系统主动发送给客户的并发通知数量方面受到限制。此限制应用于帐户,以包括帐户内的所有组。
这种速率限制可防止一个设计不佳的帐户消耗不成比例的服务器资源,从而对该服务器环境中的所有其他客户产生负面影响。
每个帐户的并发事件数已经过计算,以确保具有行为良好的 Webhook 的帐户将在最短时间内收到通知,并且很少遇到由于请求过多而延迟通知的情况。当前阈值为:
操作 |
最大 |
说明 |
Webhook 创建 |
10 |
每个帐户最多允许 10 个并发 Webhook 创建请求。 |
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
已签名文档将首先被截断,然后是参与者信息、文档信息和最终详细信息。
例如,对于协议完成事件(如果它也包括已签名文档(base 64 编码))或具有多个窗体字段的协议而言,可能会发生此情况。
Acrobat Sign Webhook 可向协议发件人以及在发送协议的组内配置的任何 Webhook 发送通知。帐户范围内的 Webhook 会接收所有事件。
侦听服务停止时重试
如果 Webhook 的目标 URL 因任何原因而停止运转,Acrobat Sign 会将 JSON 排入队列,然后在 72 小时内循序渐进地重试推送。
未传递的事件将会保留在重试队列中,并且在接下来的 72 小时内,将会尽可能按照发生顺序来传递通知。
重试传递通知的策略是:将两次尝试之间的时间增加一倍,从 1 分钟的间隔开始,增加到每 12 小时一次,进而在 72 小时内重试 15 次。
如果 Webhook 收件人无法在 72 小时内进行响应,且在过去七天没有成功传递通知,则 Webhook 将被禁用。在再次激活 Webhook 之前,不会向此 URL 发送通知。
在 Webhook 被禁用到随后再次启用期间的所有通知将丢失。