在使用 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<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 集成的关键。
以上就是获取通过邮件发送的 DocuSign Envelope 跟踪链接的详细内容，更多请关注知识资源分享宝库其它相关文章！
发表评论:
◎欢迎参与讨论，请在这里发表您的看法、交流您的观点。