信封签署 (eSign)回调说明信封事件

信封事件

当信封状态或接收人签署状态发生变化时，Tencent eSign 会向集成方配置的回调地址推送信封事件通知。回调请求体会按回调概览中的 AES-256-GCM 规则加密。

事件类型

envelope_sentevent
信封已发送，签署流程已启动 — 顺序签署模式下，仅首批签署人收到通知；并行签署模式下，所有签署人同时收到通知。
envelope_sent_failedevent
信封发送失败（大文档异步关键字解析失败或超时） — 仅包含 >60MB 文档的信封可能触发此事件。异步解析失败或超时后信封进入 sent_failed 终态，发件人可使用相同 OutEnvelopeId 重新发起发送。
envelope_completedevent
信封已完成，所有签署人均已签署 — 当最后一位签署人完成签署时触发。此时已签章 PDF 可能仍在异步生成中。若调用「查询合同下载信息」接口返回 ENVELOPE.DOWNLOAD_SIGNED_PDF_GENERATING，请稍后重试；也可订阅 envelope_pdf_signed 事件，在该事件到达后再下载。
envelope_pdf_signedevent
已签章 PDF 生成完成 — 信封完成且所有文档的已签章 PDF 均已生成完毕时触发。收到此事件后可调用「查询合同下载信息」接口下载含全部签章的最终版 PDF。
envelope_voidedevent
信封已作废（主动撤回） — 发件人在控制台或通过 API 主动撤回信封时触发。
envelope_declinedevent
信封已拒签，任一签署人拒签即触发 — 当签署人拒签时触发，信封状态变为 declined。Recipients 中包含拒签的签署人信息及拒签原因。
envelope_expiredevent
信封已过期，截止时间到期仍有签署人未完成签署 — 当设置的签署截止时间到期且仍有签署人未完成签署时自动触发。信封状态变为 voided（自动作废），Recipients 中包含所有未完成签署的签署人。
recipient_signedevent
某位签署人完成签署 — 签署人完成所有签署控件的填写并提交后触发。信封仍在签署中时 CurrentEnvelopeStatus 为 sent。
recipient_viewedevent
某位接收人查看了信封 — 签署人或抄送人首次打开信封查看时触发。同一接收人多次查看只会触发一次（首次查看时）。

载荷结构

EnvelopeCallbackPayload
EventTypestring
事件类型。envelope_sent=信封已发送，签署流程已启动（顺序签署时仅首批签署人收到通知）；envelope_sent_failed=信封发送失败（大文档异步关键字解析失败或超时，CurrentEnvelopeStatus=sent_failed，PreviousEnvelopeStatus=sending），仅包含 >60MB 文档的信封可能触发此事件；envelope_completed=信封已完成（所有签署人均已签署），此时已签章 PDF 可能仍在异步生成中；envelope_pdf_signed=已签章 PDF 生成完成，可下载含全部签章的最终版 PDF；envelope_voided=信封已作废（主动撤回）；envelope_declined=信封已拒签（任一签署人拒签即触发），Recipients 包含该签署人信息；envelope_expired=信封已过期（截止时间到期，仍有签署人未完成签署，信封自动作废，CurrentEnvelopeStatus=voided），Recipients 包含所有未完成的签署人；recipient_signed=某位签署人完成签署；recipient_viewed=某位接收人（签署人或抄送人）查看了信封
envelope_sentenvelope_sent_failedenvelope_completedenvelope_pdf_signedenvelope_voidedenvelope_declinedenvelope_expiredrecipient_signedrecipient_viewed
EnvelopeIdstring
信封 ID
OccurredAtstring
信封状态发生变更的时间，RFC3339 格式，示例：2024-01-15T10:45:00Z
PreviousEnvelopeStatusstring
状态变更前的信封状态。sending=发送中；sent=签署中（含已发送/已投递/已查看/部分签署）；sent_failed=发送失败
draftsendingsentsent_failedcompletedvoideddeclined
CurrentEnvelopeStatusstring
状态变更后的信封状态。sending=发送中（大文档异步关键字解析中）；sent=签署中（含已发送/已投递/已查看/部分签署）；sent_failed=发送失败（大文档异步关键字解析失败或超时）
draftsendingsentsent_failedcompletedvoideddeclined
VoidReasonstring
作废原因（envelope_voided / envelope_expired 事件有值）
Recipientsarray<object>
涉及本次事件的接收人列表。recipient_* 事件包含单个接收人；envelope_expired 包含所有未完成签署的签署人；其余 envelope_* 事件为空
⌃子属性
RecipientIdstring
接收人 ID
Namestring
接收人姓名
Emailstring
接收人邮箱（脱敏，如 z***@example.com）
RecipientTypestring
接收人类型。signer=签署人；carbonCopy=抄送人
signercarbonCopy
SigningOrderinteger
签署顺序（未设置顺序签署时为 0）
PreviousStatusstring
状态变更前的接收人状态
CurrentStatusstring
状态变更后的接收人状态
OperatedAtstring
操作时间，RFC3339 格式，示例：2024-01-15T11:20:00Z
DeclineReasonstring
拒签原因（仅 envelope_declined 事件有值）
FailureReasonstring
发送失败原因（仅 envelope_sent_failed 事件有值）

载荷示例

envelope_sent — 信封已发送，签署流程已启动

{
  "EventType": "envelope_sent",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T10:30:00Z",
  "PreviousEnvelopeStatus": "draft",
  "CurrentEnvelopeStatus": "sent"
}

envelope_sent_failed — 信封发送失败（大文档异步关键字解析失败或超时）

{
  "EventType": "envelope_sent_failed",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T10:35:00Z",
  "PreviousEnvelopeStatus": "sending",
  "CurrentEnvelopeStatus": "sent_failed",
  "FailureReason": "大文档异步关键字解析超时"
}

envelope_completed — 信封已完成，所有签署人均已签署

{
  "EventType": "envelope_completed",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T14:00:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "completed"
}

envelope_pdf_signed — 已签章 PDF 生成完成

{
  "EventType": "envelope_pdf_signed",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T14:00:05Z",
  "PreviousEnvelopeStatus": "completed",
  "CurrentEnvelopeStatus": "completed"
}

envelope_voided — 信封已作废（主动撤回）

{
  "EventType": "envelope_voided",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-16T09:00:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "voided",
  "VoidReason": "合同条款需要修改"
}

envelope_declined — 信封已拒签，任一签署人拒签即触发

{
  "EventType": "envelope_declined",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T15:30:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "declined",
  "Recipients": [
    {
      "RecipientId": "SGRCb1c2d3e4f5",
      "Name": "李四",
      "Email": "l***@example.com",
      "SigningOrder": 2,
      "PreviousStatus": "viewed",
      "CurrentStatus": "declined",
      "OperatedAt": "2024-01-15T15:30:00Z",
      "DeclineReason": "合同金额有误，需要修改"
    }
  ]
}

envelope_expired — 信封已过期，截止时间到期仍有签署人未完成签署

{
  "EventType": "envelope_expired",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-02-15T23:59:59Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "voided",
  "VoidReason": "签署截止时间已到期",
  "Recipients": [
    {
      "RecipientId": "SGRCc2d3e4f5g6",
      "Name": "王五",
      "Email": "w***@example.com",
      "SigningOrder": 2,
      "PreviousStatus": "sent",
      "CurrentStatus": "voided",
      "OperatedAt": "2024-02-15T23:59:59Z"
    }
  ]
}

recipient_signed — 某位签署人完成签署

{
  "EventType": "recipient_signed",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T10:45:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "sent",
  "Recipients": [
    {
      "RecipientId": "SGRCb1c2d3e4f5",
      "Name": "张三",
      "Email": "z***@example.com",
      "SigningOrder": 1,
      "PreviousStatus": "viewed",
      "CurrentStatus": "signed",
      "OperatedAt": "2024-01-15T10:45:00Z"
    }
  ]
}

recipient_viewed — 某位接收人查看了信封

{
  "EventType": "recipient_viewed",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T10:35:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "sent",
  "Recipients": [
    {
      "RecipientId": "SGRCb1c2d3e4f5",
      "Name": "张三",
      "Email": "z***@example.com",
      "SigningOrder": 1,
      "PreviousStatus": "delivered",
      "CurrentStatus": "viewed",
      "OperatedAt": "2024-01-15T10:35:00Z"
    }
  ]
}
回调概览计费事件