Envelope Events

When an envelope status or recipient signing status changes, Tencent eSign sends an envelope event notification to the callback URL configured by the integrator. The callback request body is encrypted according to the AES-256-GCM rules described in Callback Overview.

Event Types

envelope_sentevent

Envelope sent, signing process started — In sequential mode, only the first batch of signers are notified; in parallel mode, all signers are notified simultaneously.

envelope_sent_failedevent

Envelope send failed (async anchor resolve failed or timed out) — Only envelopes with documents >60MB may trigger this event. After async resolve fails or times out, the envelope enters the sent_failed terminal state. The sender can retry by re-sending with the same OutEnvelopeId.

envelope_completedevent

Envelope completed, all signers have signed — Triggered when the last signer completes. The signed PDF may still be generating asynchronously at this point. If 'Get Envelope Download Info' returns ENVELOPE.DOWNLOAD_SIGNED_PDF_GENERATING, please retry after a short delay; alternatively, subscribe to the envelope_pdf_signed event and download after it arrives.

envelope_pdf_signedevent

Signed PDF generation completed — Triggered when the envelope is completed and all documents' signed PDFs have been fully generated. After receiving this event, call 'Get Envelope Download Info' to download the final PDF with all signatures.

envelope_voidedevent

Envelope voided (manually recalled) — Triggered when the sender recalls the envelope via console or API.

envelope_declinedevent

Envelope declined by a signer — Triggered when a signer declines. Recipients includes the declining signer and reason.

envelope_expiredevent

Envelope expired, deadline passed with unsigned signers — Triggered when the signing deadline expires with pending signers. Status becomes voided. Recipients includes all unsigned signers.

recipient_signedevent

A signer has completed signing — Triggered after a signer submits all signing fields. Envelope status remains sent while other signers are pending.

recipient_viewedevent

A recipient has viewed the envelope — Triggered on first view by a signer or CC recipient. Only fires once per recipient.

Payload Structure

EnvelopeCallbackPayload

EventTypestring

Event type. envelope_sent = envelope sent, signing workflow started (in sequential signing, only the first batch of signers are notified); envelope_sent_failed = envelope send failed (async anchor resolve failed or timed out for large documents, CurrentEnvelopeStatus=sent_failed, PreviousEnvelopeStatus=sending), only envelopes with documents >60MB may trigger this event; envelope_completed = envelope completed (all signers have signed), signed PDF may still be generating asynchronously at this point; envelope_pdf_signed = signed PDF generation completed, final PDF with all signatures is ready for download; envelope_voided = envelope voided (actively recalled); envelope_declined = envelope declined (triggered when any signer declines), Recipients contains that signer's info; envelope_expired = envelope expired (deadline reached with unsigned signers, auto-voided, CurrentEnvelopeStatus=voided), Recipients contains all unsigned signers; recipient_signed = a signer completed signing; recipient_viewed = a recipient (signer or carbon copy) viewed the envelope

envelope_sentenvelope_sent_failedenvelope_completedenvelope_pdf_signedenvelope_voidedenvelope_declinedenvelope_expiredrecipient_signedrecipient_viewed

EnvelopeIdstring

Envelope ID

OccurredAtstring

Time when the envelope status changed, RFC3339 format, e.g., 2024-01-15T10:45:00Z

PreviousEnvelopeStatusstring

Envelope status before the change. sending = being sent; sent = signing in progress (includes sent/delivered/viewed/partially signed); sent_failed = send failed

draftsendingsentsent_failedcompletedvoideddeclined

CurrentEnvelopeStatusstring

Envelope status after the change. sending = being sent (async anchor resolve in progress for large documents); sent = signing in progress (includes sent/delivered/viewed/partially signed); sent_failed = send failed (async anchor resolve failed or timed out)

draftsendingsentsent_failedcompletedvoideddeclined

VoidReasonstring

Void reason (has value for envelope_voided / envelope_expired events)

Recipientsarray<object>

Recipients involved in this event. recipient_* events contain a single recipient; envelope_expired contains all unsigned signers; other envelope_* events have an empty list

⌃子属性

RecipientIdstring

Recipient ID

Namestring

Recipient name

Emailstring

Recipient email (masked, e.g., z***@example.com)

RecipientTypestring

Recipient type. signer; carbonCopy.

signercarbonCopy

SigningOrderinteger

Signing order (0 when sequential signing is not set)

PreviousStatusstring

Recipient status before the change

CurrentStatusstring

Recipient status after the change

OperatedAtstring

Operation time in RFC3339 format, e.g., 2024-01-15T11:20:00Z

DeclineReasonstring

Decline reason (only has value for envelope_declined events)

FailureReasonstring

Failure reason (only present for envelope_sent_failed events)

Payload Examples

envelope_sent — Envelope sent, signing process started

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

envelope_sent_failed — Envelope send failed (async anchor resolve failed or timed out)

{
  "EventType": "envelope_sent_failed",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T10:35:00Z",
  "PreviousEnvelopeStatus": "sending",
  "CurrentEnvelopeStatus": "sent_failed",
  "FailureReason": "Large file async keyword parsing timed out"
}

envelope_completed — Envelope completed, all signers have signed

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

envelope_pdf_signed — Signed PDF generation completed

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

envelope_voided — Envelope voided (manually recalled)

{
  "EventType": "envelope_voided",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-16T09:00:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "voided",
  "VoidReason": "Contract terms need to be updated"
}

envelope_declined — Envelope declined by a signer

{
  "EventType": "envelope_declined",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-01-15T15:30:00Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "declined",
  "Recipients": [
    {
      "RecipientId": "SGRCb1c2d3e4f5",
      "Name": "Bob",
      "Email": "l***@example.com",
      "SigningOrder": 2,
      "PreviousStatus": "viewed",
      "CurrentStatus": "declined",
      "OperatedAt": "2024-01-15T15:30:00Z",
      "DeclineReason": "Contract amount is incorrect and needs to be updated"
    }
  ]
}

envelope_expired — Envelope expired, deadline passed with unsigned signers

{
  "EventType": "envelope_expired",
  "EnvelopeId": "SGEVa1b2c3d4e5f6",
  "OccurredAt": "2024-02-15T23:59:59Z",
  "PreviousEnvelopeStatus": "sent",
  "CurrentEnvelopeStatus": "voided",
  "VoidReason": "The signing deadline has expired",
  "Recipients": [
    {
      "RecipientId": "SGRCc2d3e4f5g6",
      "Name": "Charlie",
      "Email": "w***@example.com",
      "SigningOrder": 2,
      "PreviousStatus": "sent",
      "CurrentStatus": "voided",
      "OperatedAt": "2024-02-15T23:59:59Z"
    }
  ]
}

recipient_signed — A signer has completed signing

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

recipient_viewed — A recipient has viewed the envelope

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

Callback Overview Billing Events