DocuSign已注册Webhook推送空内容，请求问题排查指导

看起来你已经完成了信封创建和待签署文档发送，但签署完成后 DocuSign 没有向你的 Webhook URL 推送任何内容，试了4次都没成功。我来帮你梳理几个常见的排查方向：

1. 确认 Webhook URL 的可访问性 #

DocuSign 的服务器需要能正常访问你的 Webhook 地址，这是最基础的前提：

• 你的 URL 必须是公网可访问的：如果是本地开发环境（比如 localhost），DocuSign 根本无法连接，建议用 ngrok 这类工具把本地端口映射到公网临时地址测试。
• 检查 SSL 证书：DocuSign 要求生产环境的 Webhook 必须使用 HTTPS，且证书是受信任的（不能是自签证书）。如果是测试环境，虽然有些情况允许 HTTP，但尽量用 HTTPS 避免问题。
• 防火墙/安全组限制：确认你的服务器没有拦截 DocuSign 的 IP 地址，或者你的云服务商（比如阿里云、AWS）的安全组规则没有阻挡 incoming 请求。

2. 检查 Webhook 的响应是否符合要求 #

DocuSign 对 Webhook 的响应有严格要求，如果不满足，可能会停止推送：

• 必须在10秒内返回 200 OK：如果你的处理逻辑太耗时（比如要做大量数据库操作），DocuSign 会认为请求失败，可能不会重试。建议先快速返回 200，再异步处理业务逻辑。
• 不要返回复杂的响应内容：只需要简单的 OK 或者空响应即可，多余的内容可能导致 DocuSign 判定响应无效。

3. 验证 DocuSign 中的 Hook 配置 #

可能是 Hook 的事件触发条件没设置对：

• 确认你勾选了**「Envelope Completed」（信封完成）**事件：如果只选了「Envelope Sent」（信封发送）这类事件，签署完成后自然不会触发推送。
• 检查 Hook 是否处于激活状态：有时候配置后可能不小心禁用了，在 DocuSign 的「Connect」页面里确认状态是 Enabled。
• 检查通知格式：DocuSign 支持 XML 和 JSON 两种格式，你的代码是否对应处理了正确的格式？比如如果选了 JSON，代码却在解析 XML，就会拿到空内容。

4. 排查 Webhook 代码的 payload 读取逻辑 #

很多时候问题出在代码没有正确读取请求体：

• 比如在 Express.js 中，默认的 body-parser 可能会自动解析请求体，但如果是 raw 格式的 payload，需要手动读取：

app.post('/docusign-webhook', (req, res) => {
  let rawBody = '';
  req.on('data', chunk => {
    rawBody += chunk.toString();
  });
  req.on('end', () => {
    console.log('收到 DocuSign 推送内容:', rawBody);
    // 这里处理业务逻辑
    res.status(200).send('OK');
  });
});

• 检查服务器日志：看看是否有 incoming 请求的记录，如果请求到达了但 payload 为空，那就是代码读取的问题；如果连请求记录都没有，那就是前面的可访问性或配置问题。

5. 用第三方工具测试推送是否正常 #

可以用 RequestBin 或者 Webhook.site 这类工具，把它们的 URL 替换成你的 Webhook URL，然后完成一次签署，看看是否能收到 DocuSign 的推送：

• 如果能收到，说明问题出在你的代码处理逻辑上；
• 如果收不到，说明是 DocuSign 配置或者 URL 可访问性的问题。

6. 查看 DocuSign 的日志 #

在 DocuSign 的管理后台，找到「Connect」->「Logs」，这里会记录所有 Webhook 推送的尝试，包括失败原因（比如连接超时、SSL 错误、非 200 响应等），根据日志信息能快速定位问题。

内容的提问来源于stack exchange，提问作者Abdul Haye