在使用 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 可以通过两种方式实现：
Account-wide 配置: 这种方式会影响你 DocuSign 账户中的所有 Envelope。你需要具有管理员权限才能进行此配置。在 DocuSign 管理界面中，找到 Connect 设置并进行配置。
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 payload) {
// 处理 DocuSign Connect Webhook 请求
System.out.println("Received DocuSign Webhook: " + payload);
// 从 payload 中提取 Envelope ID 和其他相关信息
String envelopeId = (String) ((Map) 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 集成的关键。
