Envelope events track key changes in the lifecycle of an envelope, such as creation, completion, or failure. This page describes each event type, when it occurs, and the additional data you can expect in the event payload.
The envelope.started event indicates that the envelope is ready to be sent to recipients. At this point, the envelope status changes from processing to in_progress.
The envelope.completed event is triggered when all recipients have completed (for example, signed) the envelope. At this point, the envelope status changes from in_progress to completed.
The envelope.failed event is triggered when an envelope fails, resulting in a status of failed. Use this event to handle errors or notify users of issues.The data object in the event payload includes a detail field that provides information about the failure.
Envelope failures are very rare. If an envelope fails, SignatureAPI engineers receive an automatic alert and begin investigating the issue. You can contact support for assistance or additional information about the failure.
Example event payload
JSON
Copy
Ask AI
{ "id": "evt_7c8d9e0f1g2h3i4j5k6l", "type": "envelope.failed", "timestamp": "2025-12-31T23:59:59.999Z", "data": { "object_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "object_type": "envelope", "envelope_id": "e387553d-cbb7-4924-abd8-b2d89699e9b5", "envelope_metadata": { "deal_id": "50055", "deal_owner": "Jane C." }, "detail": "The envelope failed due to an internal error. Please contact support." }}
The envelope.canceled event is triggered when the envelope is explicitly canceled by calling the Cancel Envelope endpoint. The resulting envelope status is canceled, which is a terminal state.If a reason was provided in the cancel envelope request, the data object in the event payload includes a reason property with that value. If no reason was provided, the reason property is null.
