如何从Web Hook回调函数获取参数值？Docusign信封自定义值存储与回调获取

1. 如何从Web Hook回调函数中获取参数值？ #

DocuSign的Connect Web Hook会通过POST请求把事件数据以JSON或XML格式（取决于你在Connect配置里选的格式）发送到你的指定端点。获取参数的核心步骤如下：

• 接收并解析请求体
  首先确保你的后端能处理POST请求，然后解析请求内容。比如用Python/Flask的话，你可以这样获取JSON格式的payload：

  from flask import Flask, request
  
  app = Flask(__name__)
  
  @app.route('/docusign-webhook', methods=['POST'])
  def handle_webhook():
      # 解析JSON格式的回调数据
      payload = request.get_json()
      # 提取信封状态
      envelope_status = payload['envelopeStatus']['status']
      # 提取信封ID
      envelope_id = payload['envelopeStatus']['envelopeId']
      # 提取第一个签署人的姓名
      signer_name = payload['envelopeStatus']['recipients']['signers'][0]['name']
      return 'OK', 200
  

  如果是XML格式，你需要用对应的XML解析库（比如Python的xml.etree.ElementTree）来提取字段。

• 验证回调合法性
  为了确保请求确实来自DocuSign，一定要验证回调的签名。你可以通过请求头里的X-DocuSign-Signature字段，结合你在Connect配置里设置的密钥来验证签名，避免恶意请求。

• 常用字段参考
  回调payload里最常用的字段包括：

  • envelopeStatus.status：当前信封状态（比如sent、completed、declined）
  • envelopeStatus.envelopeId：信封唯一ID
  • envelopeStatus.recipients：所有收件人的详细信息
  • envelopeStatus.timestamp：事件发生的时间戳

2. 通过API创建Docusign信封时，能否在信封引用中存储一个自定义值，且该值可从Web Hook回调函数中接收？ #

当然可以！DocuSign提供了信封级自定义字段（Envelope Custom Fields）来实现这个需求，你可以在创建信封时添加自定义键值对，这些值会自动包含在后续的Connect回调payload里。

具体实现步骤： #

• 创建信封时添加自定义字段
  在调用Envelopes::create API时，在请求体中加入customFields节点，定义你需要存储的自定义值。比如用JSON格式的请求：

  {
    "emailSubject": "请签署你的合同",
    "status": "sent",
    "customFields": {
      "textCustomFields": [
        {
          "name": "InternalOrderID",
          "value": "ORD-78901",
          "show": "false"  // 设置为false表示不在信封页面显示这个字段
        }
      ]
    },
    // 其他信封配置：文档、收件人等...
    "documents": [
      {
        "documentBase64": "BASE64_ENCODED_DOCUMENT",
        "name": "Contract.pdf",
        "documentId": "1"
      }
    ],
    "recipients": {
      "signers": [
        {
          "email": "signer@example.com",
          "name": "John Doe",
          "recipientId": "1",
          "tabs": {
            "signHereTabs": [
              {
                "documentId": "1",
                "pageNumber": "1",
                "xPosition": "100",
                "yPosition": "100"
              }
            ]
          }
        }
      ]
    }
  }
  

• 在Web Hook回调中获取自定义值
  当触发回调时，你可以从payload的envelopeStatus.customFields节点里拿到你之前设置的自定义值。比如用Python解析：

  def handle_webhook():
      payload = request.get_json()
      # 获取自定义字段的值
      custom_order_id = payload['envelopeStatus']['customFields']['textCustomFields'][0]['value']
      print(f"内部订单ID: {custom_order_id}")
      return 'OK', 200
  

其他可选方式： #

如果你只需要存储一个简单的标识符，也可以考虑使用envelopeIdPrefix（信封ID前缀），但自定义字段的灵活性更高，支持多键值对，适合存储业务相关的复杂数据。

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