Laravel集成Docusign Connect：Webhook返回的recipient_id与设置不符

开发者阿泽

2026-8-7

解决Docusign Connect回调返回默认recipient_id的问题

你遇到的问题源于Docusign的recipient_id属于平台内部标识符——即便创建签署人时指定了自定义值，系统仍可能在后续流程中重新分配顺序ID（1、2、3...）。要在回调中稳定获取自定义的签署人关联标识，应该使用client_user_id字段，这是Docusign专门提供给开发者用来关联自有系统用户的字段，会原封不动返回在Webhook payload中。

解决方案步骤：

1. 创建签署人时添加`client_user_id`字段

修改Signer实例代码，在原有参数基础上加入client_user_id，传入你需要关联的自定义ID：

$customer = new Signer([
    'email_notification' => [
        'supported_language' => $document->language->iso,
    ],
    'inherit_email_notification_configuration' => true,
    'recipient_type' => 'signer',
    'email' => $customerSignerEmail,  
    'name' => $customerSignerName,  
    'recipient_id' => 100, // 保留Docusign内部使用的ID
    'client_user_id' => 100, // 传递你的自定义关联ID
    'routing_order' => $document->document_type->customer_signing_order,
    'tabs' => $tab_customer,
]);

2. 调整Webhook回调处理逻辑

在Laravel的回调处理控制器中，读取client_user_id字段匹配数据库中的签署人，而非依赖recipient_id：

// 从回调请求中获取签署人状态
$recipientStatus = $request->input('recipientStatuses.0');
$customRecipientId = $recipientStatus['clientUserId'];

// 使用自定义ID查找并更新数据库记录
$signer = SignerModel::where('custom_id', $customRecipientId)->first();
if ($signer) {
    $signer->update(['status' => $recipientStatus['status']]);
}