DocuSign API v2.1通知负载格式变更问题求助

从2025年初开始，通过DocuSign Connect接收v2.1版本JSON通知时，原有的反序列化逻辑失效——DocuSign调整了通知的顶层结构，核心数据被收拢到data字段下，同时新增了一系列事件元数据字段。目前已有不少开发者反馈过同样的格式变更问题。

原有反序列化类（已失效） #

public class DocuSignEventNotificationResponse 
{ 
    public string status { get; set; } 
    public string envelopeId { get; set; } 
    public string documentsUri { get; set; } 
    public string recipientsUri { get; set; } 
    public Sender sender { get; set; } 
}

public class Sender 
{ 
    public string userName { get; set; } 
    public string userId { get; set; } 
    public string accountId { get; set; } 
    public string email { get; set; } 
}

新的通知负载格式示例 #

{
  "event": "envelope-completed",
  "apiVersion": "v2.1",
  "uri": "/restapi/v2.1/accounts/1e78c******8c2db/envelopes/18*******91dca",
  "retryCount": 1,
  "configurationId": 0,
  "generatedDateTime": "2025-07-16T09:49:25.5964409Z",
  "data": {
    "accountId": "1e*******c2db",
    "userId": "abcdde*******03ed7",
    "envelopeId": "1870944*********ca"
  }
}

适配新格式的C#反序列化类 #

针对新的结构，需要定义包含顶层元数据和data子对象的类：

public class DocuSignConnectNotification
{
    // C#中event是关键字，需加@前缀或用JsonProperty特性指定字段名
    public string @event { get; set; }
    public string apiVersion { get; set; }
    public string uri { get; set; }
    public int retryCount { get; set; }
    public int configurationId { get; set; }
    public DateTime generatedDateTime { get; set; }
    public NotificationData data { get; set; }
}

public class NotificationData
{
    public string accountId { get; set; }
    public string userId { get; set; }
    public string envelopeId { get; set; }
    // 不同事件类型的data字段可能有差异，比如envelope-sent会包含sender信息，可按需扩展
    // public Sender sender { get; set; }
}

// 若需要sender信息（部分事件会返回），保留原有Sender类即可
public class Sender 
{ 
    public string userName { get; set; } 
    public string userId { get; set; } 
    public string accountId { get; set; } 
    public string email { get; set; } 
}

补充说明 #

• 不同事件类型（如envelope-completed、envelope-sent）的data字段内容会有差异，可根据实际接收的通知字段扩展NotificationData类。
• DocuSign此次调整是为了统一Connect通知结构，将事件元数据与业务数据分离，便于后续功能扩展。

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