---
title: "Event"
description: "The event object records changes and actions in your account, delivered via webhooks or retrievable through the API."
canonical: "https://signatureapi.com/docs/api/resources/events/object"
source: "https://signatureapi.com/docs/api/resources/events/object.md"
last_verified_api_version: "1.18.0"
last_modified: "2026-11-18T12:10:02Z"
---

# Event

The event object records changes and actions in your account, delivered via webhooks or retrievable through the API.

_Last verified against API version 1.18.0._

Events record changes and actions in your SignatureAPI account. Examples include an [envelope completing](https://signatureapi.com/docs/api/resources/events/envelope-events#envelopecompleted) and a [recipient email bouncing](https://signatureapi.com/docs/api/resources/events/recipient-events#recipienthard_bounced).

You receive events as webhook notifications. You can also retrieve them through the API, either [for all events in your account](https://signatureapi.com/docs/api/resources/events/all) or for a [specific envelope](https://signatureapi.com/docs/api/resources/events/envelope) or [recipient](https://signatureapi.com/docs/api/resources/events/recipient).

## Typical event flow

A standard signing flow produces events in this order:

1. `envelope.created`: Envelope is created and processing begins.
2. `envelope.started`: Processing complete, recipients are being notified.
3. `recipient.released`: Recipient is ready to receive an invitation.
4. `recipient.sent`: Invitation email sent (not necessarily delivered: bounces arrive afterward as separate events). With any other authentication method, no invitation email is sent and the event fires when the ceremony becomes active.
5. `recipient.accessed`: Recipient opens the ceremony URL.
6. `recipient.viewed`: Recipient authenticates and views the documents.
7. `recipient.completed`: Recipient finishes signing.
8. `envelope.completed`: All recipients done, envelope is complete.
9. `deliverable.generated`: Signed PDF is ready for download.

For sequential routing, steps 3-7 repeat for each recipient in order. For parallel routing, multiple recipients go through steps 3-7 at the same time.

> **Note:** Events may arrive out of order. Your application should handle this gracefully. See [Webhooks](https://signatureapi.com/docs/api/webhooks) for delivery details, and the [sequence diagram](https://signatureapi.com/docs/api/resources/events/envelope-events#events-in-a-typical-run) for who triggers each step.

## Attributes

#### `id` (string)

The unique identifier of the event. Uses the `evt_` prefix.

#### `type` (enum)

The type of the event. Determines the category and the shape of the `data` payload.

Event types are grouped into four categories: envelope, recipient, deliverable, and sender.

For the full list of event types, see:

- [Envelope Events](https://signatureapi.com/docs/api/resources/events/envelope-events)
- [Recipient Events](https://signatureapi.com/docs/api/resources/events/recipient-events)
- [Deliverable Events](https://signatureapi.com/docs/api/resources/events/deliverable-events)
- [Sender Events](https://signatureapi.com/docs/api/resources/events/sender-events)

#### `timestamp` (string)

When the event occurred, in ISO 8601 format.

#### `data` (object)

The data associated with the event. The shape of this object depends on the event `type`.

**Envelope event data**

> **Info:** These properties are common to all envelope events. Some event types include additional properties. See [Envelope Events](https://signatureapi.com/docs/api/resources/events/envelope-events) for details.

#### `object_id` (string)

The unique identifier of the resource this event refers to. For envelope events, this value is the envelope ID.

#### `object_type` (enum)

The type of resource this event refers to. For envelope events, the value is `envelope`.

#### `envelope_id` (string)

The ID of the envelope this event refers to. For envelope events, this value is the same as `object_id`.

#### `envelope_metadata` (object)

The metadata attached to the envelope.

**Recipient event data**

> **Info:** These properties are common to all recipient events. Some event types include additional properties. See [Recipient Events](https://signatureapi.com/docs/api/resources/events/recipient-events) for details.

#### `object_id` (string)

The unique identifier of the resource this event refers to. For recipient events, this value is the recipient ID.

#### `object_type` (enum)

The type of resource this event refers to. For recipient events, the value is `recipient`.

#### `envelope_id` (string)

The ID of the envelope the recipient belongs to.

#### `envelope_metadata` (object)

The metadata attached to the envelope the recipient belongs to.

#### `recipient_type` (enum)

The type of the recipient. Possible values: `signer`, `qualified_signer`, `approver`, `preparer`, `automatic_signer`.

#### `recipient_key` (string)

A user-provided key that identifies the recipient within an envelope.

**Deliverable event data**

> **Info:** These properties are common to all deliverable events. Some event types include additional properties. See [Deliverable Events](https://signatureapi.com/docs/api/resources/events/deliverable-events) for details.

#### `object_id` (string)

The unique identifier of the resource this event refers to. For deliverable events, this value is the deliverable ID.

#### `object_type` (enum)

The type of resource this event refers to. For deliverable events, the value is `deliverable`.

#### `envelope_id` (string)

The ID of the envelope the deliverable belongs to.

#### `envelope_metadata` (object)

The metadata attached to the envelope the deliverable belongs to.

#### `deliverable_type` (enum)

The type of the deliverable. Possible values: `simple`, `standard`.

#### `deliverable_name` (string | null)

A user-provided name for the deliverable.

#### `included_documents` (array)

The keys of the documents included in the deliverable.

**Sender event data**

> **Info:** These properties are common to all sender events. Some event types include additional properties. See [Sender Events](https://signatureapi.com/docs/api/resources/events/sender-events) for details.

#### `object_id` (string)

The unique identifier of the sender this event refers to.

#### `object_type` (enum)

The type of resource this event refers to. For sender events, the value is `sender`.

#### `email` (string)

The email address of the sender this event refers to.

### Example: Recipient event

Response 200 OK:

```json
{
  "id": "evt_7BFIYuMgWzJ1AHscS0RNxC",
  "type": "recipient.completed",
  "timestamp": "2026-11-02T15:21:39.000Z",
  "data": {
    "object_id": "re_49r1R2jpPDz8hSpP75ZkPp",
    "object_type": "recipient",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "envelope_metadata": {
      "deal_id": "D-1042",
      "deal_owner": "Sam P."
    },
    "recipient_type": "signer",
    "recipient_key": "client",
    "session_id": "ses_1chIEkLOtmUMSdo0aL8p9A"
  }
}
```

### Example: Envelope event

Response 200 OK:

```json
{
  "id": "evt_4GpGD1cNnrkemsTLAvPW9G",
  "type": "envelope.completed",
  "timestamp": "2026-11-02T15:21:40.000Z",
  "data": {
    "object_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "object_type": "envelope",
    "envelope_id": "eb4cf433-a8af-4161-b37b-7ef57d423e56",
    "envelope_metadata": {
      "deal_id": "D-1042",
      "deal_owner": "Sam P."
    }
  }
}
```
