获取通过邮件发送的 DocuSign Envelope 跟踪链接

在使用 DocuSign API 将签名请求通过电子邮件发送给接收者时，你可能需要跟踪 Envelope 的状态，例如是否已发送、已查看、已签名或已完成。虽然 DocuSign 会自动发送包含签名链接的电子邮件，但直接获取这个链接以便在你的应用程序中进行跟踪和管理，需要一些额外的配置。

本教程将指导你如何使用 DocuSign Connect Webhooks 来实现这个目标。

DocuSign Connect Webhooks 的工作原理

DocuSign Connect 是一种 Webhook 服务，允许你在 Envelope 状态发生变化时，接收来自 DocuSign 的实时通知。你可以配置 Connect 来监听特定的 Envelope 事件，例如：

• Envelope 创建
• Envelope 发送
• Envelope 查看
• Envelope 签名
• Envelope 完成
• Envelope 作废

当这些事件发生时，DocuSign 会向你预先配置的 URL 发送一个 http POST 请求，其中包含关于 Envelope 状态的详细信息。

配置 DocuSign Connect

配置 DocuSign Connect 可以通过两种方式实现：

1. Account-wide 配置: 这种方式会影响你 DocuSign 账户中的所有 Envelope。你需要具有管理员权限才能进行此配置。在 DocuSign 管理界面中，找到 Connect 设置并进行配置。

2. Per-envelope 配置: 这种方式允许你为单个 Envelope 指定 Connect 设置。这需要在创建 Envelope 时，通过 API 请求中的 eventNotifications 属性进行配置。

Per-envelope 配置示例 (JSON)

以下是一个 eventNotifications 属性的示例，用于配置 Connect 监听 Envelope 的完成事件：

{   "eventNotifications": {     "url": "https://your-server.com/docusign-webhook",     "includeData": true,     "includeDocuments": false,     "events": [       {         "envelopeEvent": "envelopeCompleted"       }     ],     "connectCustomConfigurationId": "YOUR_CONNECT_CONFIGURATION_ID" // 可选，如果使用已存在的 Connect 配置   } }

解释：

• url: 这是你的服务器监听 DocuSign Webhook 请求的 URL。
• includeData: 指定是否包含 Envelope 数据。设置为 true 会包含 Envelope 的详细信息。
• includeDocuments: 指定是否包含文档。设置为 false 通常更安全，因为文档可能包含敏感信息。
• events: 一个事件列表，指定你需要监听的事件。
• envelopeEvent: 指定具体的 Envelope 事件。 envelopeCompleted 表示监听 Envelope 完成事件。
• connectCustomConfigurationId: 可选。如果你已经创建了一个 Connect 配置，可以通过 ID 来引用它。

服务器端实现

你需要创建一个服务器端点来接收 DocuSign Connect 的 Webhook 请求。这个端点需要能够处理 HTTP POST 请求，并解析请求体中的 json 数据。

示例代码 (Java)

以下是一个使用 spring Boot 框架实现的简单示例：

import org.springframework.web.bind.annotation.PostMapping; import org.springframework.web.bind.annotation.RequestBody; import org.springframework.web.bind.annotation.RestController;  import java.util.Map;  @RestController public class DocuSignWebhookController {      @PostMapping("/docusign-webhook")     public void handleDocuSignWebhook(@RequestBody Map<String, Object> payload) {         // 处理 DocuSign Connect Webhook 请求         System.out.println("Received DocuSign Webhook: " + payload);          // 从 payload 中提取 Envelope ID 和其他相关信息         String envelopeId = (String) ((Map<String, Object>) payload.get("envelopeInfo")).get("envelopeId");          // 在这里你可以将 Envelope ID 存储到数据库中，或者执行其他操作         System.out.println("Envelope ID: " + envelopeId);     } }

注意事项

• 安全性: 确保你的 Webhook 端点是安全的，并且只接受来自 DocuSign 的请求。可以使用 DocuSign 提供的签名验证机制来验证请求的真实性。
• 错误处理: 在你的 Webhook 端点中实现适当的错误处理机制，以便在发生错误时进行重试或记录错误信息。
• 性能: 确保你的 Webhook 端点能够快速处理请求，以避免 DocuSign 超时。
• DocuSign Connect 限制: DocuSign Connect 可能会受到速率限制，具体取决于你的 DocuSign 计划。请查阅 DocuSign 文档以了解更多信息。
• 获取 Envelope 链接: 虽然 Connect 主要用于接收状态更新，但通过 Envelope ID，你可以使用 DocuSign API 获取 Envelope 的详细信息，包括签名链接（如果适用）。

总结

使用 DocuSign Connect Webhooks 是跟踪通过电子邮件发送的 DocuSign Envelope 状态的有效方法。通过配置 Connect 来监听特定的事件，并在你的服务器上创建一个 Webhook 端点来接收通知，你可以实时了解 Envelope 的状态，并在你的应用程序中执行相应的操作。记住，安全性、错误处理和性能是实现一个可靠的 DocuSign Connect 集成的关键。