如何在Spring Boot应用中对接DocuSign Connect webhook并接收回调

开发者阿泽

2026-9-24

该需求完全可以实现，具体落地步骤如下：

具体实现步骤

编写回调接收接口
在Spring Boot项目中新增一个POST类型的HTTP接口，用于接收DocuSign推送的回调数据，示例代码如下：

import org.springframework.http.MediaType;
import org.springframework.http.ResponseEntity;
import org.springframework.web.bind.annotation.PostMapping;
import org.springframework.web.bind.annotation.RequestBody;
import org.springframework.web.bind.annotation.RequestMapping;
import org.springframework.web.bind.annotation.RestController;

@RestController
@RequestMapping("/webhook")
public class DocuSignWebhookController {

    @PostMapping(value = "/docusign/callback", consumes = MediaType.APPLICATION_JSON_VALUE)
    public ResponseEntity<Void> receiveCallback(@RequestBody String callbackPayload) {
        // 1. 先做请求来源验签
        // 2. 解析callbackPayload处理业务逻辑
        // 3. 处理完成返回200状态码即可
        return ResponseEntity.ok().build();
    }
}

配置请求验签逻辑
为了避免伪造的回调请求，建议你在DocuSign Connect配置页面开启HMAC签名校验，设置自定义的HMAC密钥并保存在Spring Boot项目的配置文件中。收到回调请求后，先从请求头中获取DocuSign生成的签名，和本地用HMAC密钥、原始请求体计算出的签名做对比，校验通过再处理业务逻辑。
处理回调业务逻辑
验签通过后，你可以把回调的JSON报文映射为对应的Java实体类，提取信封ID、签署人状态、签署时间等你需要的字段，处理自身业务（如更新合同状态、发送签署完成通知等），处理完成后返回200状态码即可，如果返回非2xx状态码，DocuSign会按照规则重试回调请求。

注意事项

本地调试阶段需要将你的服务端口暴露到公网，可以用内网穿透工具实现，确保DocuSign的请求可以访问到你的接口，生产环境直接使用公网可访问的服务域名即可。
回调处理逻辑需要做幂等控制，可使用回调报文中的信封ID+事件类型作为幂等键，避免网络波动导致的重复回调触发重复业务处理。
如果需要接收XML格式的回调，只需要修改接口的consumes属性为MediaType.APPLICATION_XML_VALUE，同时配置对应的XML解析依赖即可。

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