咨询DocuSign Envelope Connect消息格式为JSON的配置问题

核心问题 #

通过DocuSign API创建信封时，已在eventNotification中指定JSON格式的Webhook消息，但始终收到XML格式；尝试切换到SIM事件模型的events属性后，完全收不到状态更新。

排查与解决步骤 #

1. 检查账户级Connect全局配置的优先级 #

DocuSign账户级的Connect全局订阅会覆盖单个信封的eventNotification设置。如果你的账户存在全局Webhook订阅，且该订阅设置为XML格式，那么即使信封单独配置了JSON，也会被全局规则覆盖。

• 操作：登录DocuSign管理后台，进入「Connect」页面，查看所有已启用的全局订阅。
  • 若存在针对所有信封的全局订阅，检查其消息格式设置，将其改为JSON；
  • 或调整该订阅的触发范围（例如仅针对特定模板/信封），避免与信封级配置冲突。

2. 验证API版本与eventNotification格式 #

• 确保你调用的是REST v2.1及以上版本的创建信封API（请求URL示例：https://demo.docusign.net/restapi/v2.1/accounts/{accountId}/envelopes），因为eventData.format仅在v2.1+版本中生效。
• 区分传统事件模型与SIM事件模型的正确用法：
  • 传统模型：使用envelopeEvents+recipientEvents，通过eventData.format指定JSON格式（你的原始配置属于这种，需确保API版本正确）；
  • SIM模型：使用events属性，仅支持JSON格式，但需注意事件类型的写法（如"eventType": "envelope.completed"而非envelopeEventStatusCode），正确示例：

    "eventNotification": {
      "url": "https://webhook.site/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
      "events": [
        {"eventType": "envelope.completed"},
        {"eventType": "envelope.declined"},
        {"eventType": "envelope.voided"},
        {"eventType": "recipient.completed"}
      ],
      "eventData": {
        "format": "json",
        "includeData": ["custom_fields"],
        "version": "restv2.1"
      },
      "requireAcknowledgment": true,
      "loggingEnabled": true
    }
    

3. 分析Connect日志 #

从你提到的Connect日志中，重点查看：

• 消息格式字段是否确实为XML；
• 「配置来源」字段，判断是使用了账户级配置还是信封级配置。若来源是账户级，优先调整全局订阅；若为信封级，检查API请求是否正确传递了eventNotification参数（可通过API请求日志验证）。

4. 验证信封的eventNotification配置 #

调用GET /accounts/{accountId}/envelopes/{envelopeId}接口，查看返回结果中的eventNotification字段，确认你设置的JSON格式配置是否被正确保存到信封中。

内容的提问来源于stack exchange，提问作者Johnathan Knutson