Events - FlowSign

Every delivery has the same envelope. event is one of the names below and data is that event’s payload.

{
  "event": "SESSION_COMPLETED",
  "timestamp": "2026-09-17T01:15:02.318Z",
  "data": { ... }
}

string

required

The event name.

string

required

When the event was raised, ISO 8601 in UTC.

object

required

Event-specific payload, documented per event below.

Package events describe the package as a whole. Session events describe one recipient’s turn on a package. A recipient’s recipientName and recipientEmail are nullable because a session can exist before the recipient is known. Every event also carries the package’s custom field values:

object

required

The package’s custom field values, keyed by the custom field’s key. Only fields with a value appear; {} when none are set. Keys are managed under Settings → Custom fields.

The same schemas are published in the OpenAPI spec as WebhookPayload_<EVENT> components, so you can generate types for your listener.

Package events

PACKAGE_SENT

Raised once when a package is sent and its signing sessions are created.

string

required

string

required

integer

required

Number of recipients who must act on the package.

integer

required

Number of sessions invited immediately. Lower than signerCount when recipients sign in order.

{
  "event": "PACKAGE_SENT",
  "timestamp": "2026-09-17T01:12:50.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "packageTitle": "Employment agreement: Ana Reid",
    "signerCount": 2,
    "sessionsSent": 1,
    "metadata": { "employee_id": "E-1042" }
  }
}

PACKAGE_COMPLETED

Raised when the last recipient finishes and the package becomes COMPLETED.

string

required

string

required

string

required

ISO 8601 timestamp.

{
  "event": "PACKAGE_COMPLETED",
  "timestamp": "2026-09-17T03:40:11.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "packageTitle": "Employment agreement: Ana Reid",
    "completedAt": "2026-09-17T03:40:10.884Z",
    "metadata": { "employee_id": "E-1042" }
  }
}

PACKAGE_DECLINED

Raised when a recipient’s decline ends the package as DECLINED.

string

required

string

required

string | null

required

The reason the recipient gave, if any.

{
  "event": "PACKAGE_DECLINED",
  "timestamp": "2026-09-17T02:05:30.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "packageTitle": "Employment agreement: Ana Reid",
    "reason": "Start date is wrong",
    "metadata": { "employee_id": "E-1042" }
  }
}

PACKAGE_VOIDED

Raised when a package is voided by a member or through the API.

string

required

string

required

Email address of the member who voided it, or system.

{
  "event": "PACKAGE_VOIDED",
  "timestamp": "2026-09-17T02:30:00.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "voidedBy": "[email protected]",
    "metadata": { "employee_id": "E-1042" }
  }
}

PACKAGE_EXPIRED

Raised when a package passes its expiry date unsigned.

string

required

string

required

{
  "event": "PACKAGE_EXPIRED",
  "timestamp": "2026-10-17T00:00:05.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "packageTitle": "Employment agreement: Ana Reid",
    "metadata": { "employee_id": "E-1042" }
  }
}

Session events

All session events share these fields:

string

required

string

required

Matches recipientSessions[].id on GET /api/v1/packages/{packageId}.

string | null

required

string | null

required

SESSION_SENT

Raised when a recipient’s invitation is sent. In a sequential package this happens when it becomes their turn.

string

required

{
  "event": "SESSION_SENT",
  "timestamp": "2026-09-17T01:12:50.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "sessionId": "ses_71ab",
    "recipientName": "Ana Reid",
    "recipientEmail": "[email protected]",
    "packageTitle": "Employment agreement: Ana Reid",
    "metadata": { "employee_id": "E-1042" }
  }
}

SESSION_OPENED

Raised when the recipient opens their session. Carries the shared fields only.

{
  "event": "SESSION_OPENED",
  "timestamp": "2026-09-17T01:20:14.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "sessionId": "ses_71ab",
    "recipientName": "Ana Reid",
    "recipientEmail": "[email protected]",
    "metadata": { "employee_id": "E-1042" }
  }
}

SESSION_COMPLETED

Raised when the recipient finishes their session.

string

required

{
  "event": "SESSION_COMPLETED",
  "timestamp": "2026-09-17T01:26:02.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "sessionId": "ses_71ab",
    "recipientName": "Ana Reid",
    "recipientEmail": "[email protected]",
    "packageTitle": "Employment agreement: Ana Reid",
    "metadata": { "employee_id": "E-1042" }
  }
}

SESSION_DECLINED

Raised when the recipient declines to sign. A PACKAGE_DECLINED event follows when the decline ends the package.

string

required

string | null

required

The reason the recipient gave, if any.

{
  "event": "SESSION_DECLINED",
  "timestamp": "2026-09-17T02:05:29.000Z",
  "data": {
    "packageId": "pkg_9f3c2e",
    "sessionId": "ses_71ab",
    "recipientName": "Ana Reid",
    "recipientEmail": "[email protected]",
    "packageTitle": "Employment agreement: Ana Reid",
    "reason": "Start date is wrong",
    "metadata": { "employee_id": "E-1042" }
  }
}

​Package events

​PACKAGE_SENT

​PACKAGE_COMPLETED

​PACKAGE_DECLINED

​PACKAGE_VOIDED

​PACKAGE_EXPIRED

​Session events

​SESSION_SENT

​SESSION_OPENED

​SESSION_COMPLETED

​SESSION_DECLINED

Package events

PACKAGE_SENT

PACKAGE_COMPLETED

PACKAGE_DECLINED

PACKAGE_VOIDED

PACKAGE_EXPIRED

Session events

SESSION_SENT

SESSION_OPENED

SESSION_COMPLETED

SESSION_DECLINED