Envelope events

Track envelope lifecycle changes including creation, completion, cancellation, and failure.

Envelope events track key changes in the lifecycle of an envelope. This page describes each event type, when it fires, and the additional data included in the payload.

envelope.created

Fires when a new envelope is created. The envelope is in processing status and has not yet been sent to recipients.

Use this event to record that a signing process has started in your system.

Example payload

JSON

{
    "id": "evt_4p2oouvNvjp1I9ckgqycH2",
    "type": "envelope.created",
    "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."
        }
    }
}

envelope.started

Fires when the envelope finishes processing and transitions from processing to in_progress status. Recipients are now being notified.

For sequential routing, the first recipient receives the signing request. For parallel routing, all recipients receive it at the same time.

Example payload

JSON

{
    "id": "evt_5a2b3c4d5e6f7g8h9i0j",
    "type": "envelope.started",
    "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."
        }
    }
}

envelope.completed

Fires when all recipients have completed the envelope. The envelope status changes from in_progress to completed.

Use this event to trigger downstream workflows such as storing signed documents, updating records, or notifying your team.

Example payload

JSON

{
    "id": "evt_6b7c8d9e0f1g2h3i4j5k",
    "type": "envelope.completed",
    "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."
        }
    }
}

envelope.failed

Fires when an envelope encounters an internal error and transitions to failed status. The data.detail property contains a human-readable explanation of the failure.

Envelope failures are very rare. SignatureAPI engineers receive an automatic alert and begin investigating when this event fires. Contact support for additional information.

Example payload

JSON

{
    "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": "Could not parse input PDF document."
    }
}

envelope.canceled

Fires when the envelope is explicitly canceled by calling the Cancel Envelope endpoint. The envelope status changes to canceled, which is a terminal state.

The data.reason property contains the cancellation reason if one was provided, or null if none was given.

Example payload

JSON

{
    "id": "evt_8d9e0f1g2h3i4j5k6l7m",
    "type": "envelope.canceled",
    "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."
        },
        "reason": "Insurance policy offer expired."
    }
}