SuperAPI AI 工具集

docusign-webhooks

编程与开发

查看项目

更新于 10-16 05:52

技能介绍

用途:接收并验证 DocuSign Connect Webhook,适用于搭建 Connect 处理程序、调试 HMAC 签名验证失败、理解信封与收件人事件类型及负载、处理 envelope-completed、recipient-completed 等事件,以及验证 X-DocuSign-Signature-1 请求头。

验证方式:DocuSign Connect 用 Connect HMAC 密钥对原始请求体做 HMAC-SHA256,并将摘要以 base64 放在 X-DocuSign-Signature-1 头中。多个 HMAC 密钥同时启用时会发送多个头(X-DocuSign-Signature-1 至最多 100),只需其中一个匹配即可。x-authorization-digest 头指明算法(HMACSHA256)。这不是 Standard Webhooks 规范。事件类型位于 JSON 体的 event 字段(如 envelope-completed),不在头中。

重要限制:必须对 DocuSign 发送的精确原始字节验证;任何重新序列化(美化打印、JSON 往返)都会改变字节并破坏签名。

常见事件类型使用连字符的资源-动作格式:envelope-sent、envelope-delivered、envelope-completed、envelope-declined、envelope-voided、recipient-sent、recipient-delivered、recipient-completed、recipient-declined、recipient-authenticationfailed。完整列表见 references/overview.md。

环境变量:DOCUSIGN_HMAC_SECRET=your_connect_hmac_secret(来自 eSignature Admin > Connect > keys)。

本地开发:npx hookdeck-cli listen 3000 docusign --path /webhooks/docusign,将打印的 URL 作为 Connect 配置的发布 URL。

参考材料:references/overview.md、references/setup.md、references/verification.md。建议搭配 webhook-handler-patterns 技能,处理程序顺序、幂等性(DocuSign 重试最长 15 天)、错误处理与重试逻辑。