用户指南 取消(C)

配置 Webhook

概述

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 详细信息的开发人员可通过以下网址找到更多信息:

使用方式

管理员首先需要拥有 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 捕捉的网络范围是多少?“帐户”和“组”在界面中可用。
    • 此 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。
    • 已启用位于多个组的用户的帐户将看到设置应该应用于范围组的选项。
  • 用户帐户:触发推送的用户帐户触发器的所有已订阅事件。用户级别 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 将使用来自合作伙伴应用程序帐户的客户端证书(如果可用)来识别自身身份。

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

Web 服务器验证

注册 Webhook 期间,Acrobat Sign 会验证 Webhook 服务器 URL。

如果无法从 Acrobat Sign 完成与 Webhook 回调 URL 的连接,则客户将无法注册 Webhook。

客户端证书验证

如何启用或禁用

默认情况下,对于企业计划帐户,已启用访问 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 的当前身份验证和可见性模型,这意味着用户仅在他们开始参与协议时有权访问协议。

侦听服务停止时重试

如果 Webhook 的目标 URL 因任何原因而停止运转,Acrobat Sign 会将 JSON 排入队列,然后在 72 小时内循序渐进地重试推送。

未传递的事件将会保留在重试队列中,并且在接下来的 72 小时内,将会尽可能按照发生顺序来传递通知。

重试传递通知的策略是:将两次尝试之间的时间增加一倍,从 1 分钟的间隔开始,增加到每 12 小时一次,进而在 72 小时内重试 15 次。

如果 Webhook 收件人无法在 72 小时内进行响应,且在过去七天没有成功传递通知,则 Webhook 将被禁用。在再次激活 Webhook 之前,不会向此 URL 发送通知。

在 Webhook 被禁用到随后再次启用期间的所有通知将丢失。

更快、更轻松地获得帮助

新用户?