> ## Documentation Index
> Fetch the complete documentation index at: https://signatureapi-daf4ee54.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "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."
          }
      }
  }
  ```
</Accordion>

## 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.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "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."
          }
      }
  }
  ```
</Accordion>

## 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.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "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."
          }
      }
  }
  ```
</Accordion>

## 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.

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

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "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."
      }
  }
  ```
</Accordion>

## envelope.canceled

Fires when the envelope is explicitly canceled by calling the [Cancel Envelope](/docs/api/resources/envelopes/cancel) 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.

<Accordion title="Example payload">
  ```json JSON theme={null}
  {
      "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."
      }
  }
  ```
</Accordion>