用途:配置并处理 Documenso Webhook,实时接收文档生命周期通知。支持的事件包括 document.created、sent、opened、signed、completed、rejected、cancelled,分别对应审计记录、SLA 计时、参与度跟踪、签署进度、完成触发下游流程、拒签告警与取消清理等场景。
前提:Documenso 团队账户(Webhook 需 teams 及以上方案)、HTTPS 接收端点、已完成 documenso-install-auth 设置。
配置与用法:在 Team Settings > Webhooks 创建 Webhook,填写 HTTPS 端点、勾选事件,可选填 Webhook 密钥,该值原样放在每次请求的 X-Documenso-Secret 头中。处理端应先用恒定时间比较校验共享密钥(非 HMAC 签名),再解析事件;随立刻返回 200,异步处理业务逻辑。
可靠性与限制:需用不透明事件 ID 做幂等去重(生产环境建议存 Redis 或数据库,而非内存 Set),按文档超时时间内确认,日志仅记录状态与结果元数据,瞬时错误做有界退避重试,终态失败隔离,不要盲目重放签署动作。本地开发可用 ngrok http 3000 暴露 HTTPS 地址,并用 curl 模拟投递测试。
常见错误:401 多为密钥不匹配;收不到事件常见于端点非 HTTPS;重复处理需幂等;处理超时应先 200 再入队异步;事件停止到达应检查 Webhook 是否被停用。性能优化见 documenso-performance-tuning。其他细节资料暂未提供。