---
title: "Event reference"
description: "Signer webhook event reference: body format, the fields of each event, field types and a sample of every event."
canonical: "https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events"
locale: "en"
product: "Signer"
last_updated: "2026-10-22"
---

# Event reference

Signer sends an event to the webhook URL when something happens to a document, such as a signature or the
end of the flow. Each event carries the event type and the document data. To register the webhook and
create the endpoint that receives the events, see [Webhooks](https://docs.lacunasoftware.com/en-us/articles/signer/webhooks).

## Request format

Signer sends a `POST` with `Content-Type: application/json` (UTF-8). The body always has two fields:

```json
{
  "type": "DocumentConcluded",
  "data": { }
}
```

| Field | Type | Description |
|---|---|---|
| `type` | text | The event type. See the list in [Events](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#events). |
| `data` | object | The event data. Its content depends on the `type`. |

The body follows these conventions:

* Field names are in camelCase, such as `creationDate`.
* Enumeration values come as text. For example, Signer sends `"DocumentConcluded"`, not `1`.
* Dates use the ISO 8601 format, with the time zone, such as `2026-09-10T14:27:35.115Z`.
* Ids such as `id`, `userId` and `flowActionId` are GUIDs as text.

In the tables on this page, a field that can come as `null` has "or `null`" in the "Type" column.

## Events

| `type` | When Signer sends it |
|---|---|
| [`DocumentsCreated`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentscreated) | One or more documents were created. |
| [`DocumentSigned`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentsigned) | A participant signed the document. |
| [`DocumentApproved`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentapproved) | A participant approved the document. |
| [`DocumentRefused`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentrefused) | A participant refused the document. |
| [`DocumentConcluded`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentconcluded) | The flow finished: every action was completed. |
| [`DocumentCanceled`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentcanceled) | The document was canceled. |
| [`DocumentPaused`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentpaused) | The document was paused. |
| [`DocumentResumed`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentresumed) | A paused document was resumed. |
| [`DocumentExpired`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentexpired) | The document reached its expiration date without being concluded. |
| [`DocumentDeleted`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#documentdeleted) | One or more documents were deleted. |
| [`InvoiceClosed`](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#invoiceclosed) | An invoice was closed. |

## Common fields of document events

Every document event carries the fields below in `data`. In the `DocumentsCreated` and `DocumentDeleted`
events, each item of the `documents` list carries these fields.

| Field | Type | Description |
|---|---|---|
| `id` | text (GUID) | The document id. |
| `name` | text | The document name. |
| `creationDate` | date | The date the document was created. |
| `updateDate` | date | The date of the last change to the document. |
| `folder` | object or `null` | The document folder. It is `null` when the document is not in a folder. |
| `folder.id` | text (GUID) | The folder id. |
| `folder.name` | text | The folder name. |
| `folder.parentId` | text (GUID) or `null` | The id of the folder above this one. It is `null` when the folder is not inside another folder. |
| `folder.organizationName` | text | The name of the folder's organization. |
| `organization` | object or `null` | The document organization. It is `null` for personal documents. |
| `organization.id` | text (GUID) | The organization id. |
| `organization.name` | text | The organization name. |
| `organization.identifier` | text | The organization's CNPJ (Brazilian company tax id). |
| `organization.owner` | object or `null` | The owner of a personal organization, with `id` and `name`. It is `null` for other organizations. |
| `createdBy` | object | The user or application that created the document, with `id` and `name`. |

```json
{
  "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
  "name": "Services agreement",
  "creationDate": "2026-09-10T13:02:11.482Z",
  "updateDate": "2026-09-10T14:27:35.115Z",
  "folder": {
    "id": "0a9e1f3c-2b44-4f6a-9d0e-77c1b8a4e510",
    "name": "Contracts 2026",
    "parentId": null,
    "organizationName": "Acme Inc."
  },
  "organization": {
    "id": "5f2c9a71-3e8d-4a12-bb90-6d4e2f1c8a33",
    "name": "Acme Inc.",
    "identifier": "11222333000181",
    "owner": null
  },
  "createdBy": {
    "id": "4d961566-9b03-450c-b144-930e0294bac2",
    "name": "ERP Integration"
  }
}
```

To keep them short, the samples in the sections below show only `id` and `name` from the common fields.

## Who acted

Events use two objects to tell who acted.

The participant object appears in `signature`, `approval` and `refusal`:

| Field | Type | Description |
|---|---|---|
| `flowActionId` | text (GUID) | The id of the flow action, for example the participant's signing step. In `refusal`, it can be `null`. |
| `date` | date | The date of the action. |
| `userId` | text (GUID) | The id of the user who acted. |
| `name` | text | The user name. |
| `identifier` | text | The user identifier, for example the CPF (Brazilian individual tax id). |
| `emailAddress` | text | The user email address. |
| `reason` | text | The refusal reason. Only in `refusal`. |

The agent object appears in `canceledBy`, `pausedBy` and `resumedBy`. An agent is a user or an
application:

| Field | Type | Description |
|---|---|---|
| `id` | text (GUID) | The id of the user or application. |
| `name` | text | The name of the user or application. |
| `type` | text | `User` for a user, or `Application` for an application. |

## Document events

### DocumentsCreated

Signer sends this event when one or more documents are created. One event can carry several documents. In
this event, `data` has only the `documents` list, with no common fields outside it.

| Field | Type | Description |
|---|---|---|
| `documents` | list | The created documents. Each item has the [common fields](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#common-fields-of-document-events). |

```json
{
  "type": "DocumentsCreated",
  "data": {
    "documents": [
      { "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11", "name": "Contract 1" },
      { "id": "c98a2f14-1d3b-4c77-8e05-2a6b9d1f4e62", "name": "Contract 2" }
    ]
  }
}
```

### DocumentSigned

Signer sends this event when a participant signs the document. If the document has several signers,
Signer sends one event for each signature.

| Field | Type | Description |
|---|---|---|
| `signature` | object | The participant who signed. See the [participant object](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#who-acted). |

```json
{
  "type": "DocumentSigned",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "signature": {
      "flowActionId": "4bf61c68-eaf1-455f-b4a1-6141554f1dae",
      "date": "2026-09-10T14:27:35.115Z",
      "userId": "8c3a1d90-77b5-4e2f-9a61-0f5d2b7c4e88",
      "name": "John Wick",
      "identifier": "81976153069",
      "emailAddress": "john.wick@mailinator.com"
    }
  }
}
```

### DocumentApproved

Signer sends this event when a participant approves the document.

| Field | Type | Description |
|---|---|---|
| `approval` | object | The participant who approved. See the [participant object](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#who-acted). |

```json
{
  "type": "DocumentApproved",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "approval": {
      "flowActionId": "7d2e9b41-0c6a-4f18-a3b5-92e1c4d7f630",
      "date": "2026-09-10T13:45:20.310Z",
      "userId": "2f7b4c18-6e9d-4a35-8b02-c1d6e9a3f574",
      "name": "Mary Smith",
      "identifier": "52998224725",
      "emailAddress": "mary.smith@mailinator.com"
    }
  }
}
```

### DocumentRefused

Signer sends this event when a participant refuses the document.

| Field | Type | Description |
|---|---|---|
| `refusal` | object | The participant who refused, with the `reason` field. See the [participant object](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#who-acted). Here, `flowActionId` can be `null`. |

```json
{
  "type": "DocumentRefused",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "refusal": {
      "flowActionId": "4bf61c68-eaf1-455f-b4a1-6141554f1dae",
      "date": "2026-09-10T15:11:02.700Z",
      "userId": "8c3a1d90-77b5-4e2f-9a61-0f5d2b7c4e88",
      "name": "John Wick",
      "identifier": "81976153069",
      "emailAddress": "john.wick@mailinator.com",
      "reason": "Wrong amount in clause 4"
    }
  }
}
```

### DocumentConcluded

Signer sends this event when the flow finishes, that is, when every action of the document was completed.
The event has only the [common fields](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#common-fields-of-document-events).

```json
{
  "type": "DocumentConcluded",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement"
  }
}
```

### DocumentCanceled

Signer sends this event when a user or an application cancels the document.

| Field | Type | Description |
|---|---|---|
| `canceledBy` | object | Who canceled. See the [agent object](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#who-acted). |
| `reason` | text | The cancellation reason. |

```json
{
  "type": "DocumentCanceled",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "canceledBy": {
      "id": "4d961566-9b03-450c-b144-930e0294bac2",
      "name": "ERP Integration",
      "type": "Application"
    },
    "reason": "Agreement replaced by a new version"
  }
}
```

### DocumentPaused

Signer sends this event when a user pauses the document. The event exists since Signer version 3.0.0.

| Field | Type | Description |
|---|---|---|
| `pausedBy` | object | Who paused. See the [agent object](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#who-acted). |
| `reason` | text | The reason given when pausing. |

```json
{
  "type": "DocumentPaused",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "pausedBy": {
      "id": "2f7b4c18-6e9d-4a35-8b02-c1d6e9a3f574",
      "name": "Mary Smith",
      "type": "User"
    },
    "reason": "Waiting for legal review"
  }
}
```

### DocumentResumed

Signer sends this event when a user resumes a paused document. The event exists since Signer version
3.0.0.

| Field | Type | Description |
|---|---|---|
| `resumedBy` | object | Who resumed. See the [agent object](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#who-acted). |

```json
{
  "type": "DocumentResumed",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "resumedBy": {
      "id": "2f7b4c18-6e9d-4a35-8b02-c1d6e9a3f574",
      "name": "Mary Smith",
      "type": "User"
    }
  }
}
```

### DocumentExpired

Signer sends this event when the document reaches its expiration date and the flow has not finished.

| Field | Type | Description |
|---|---|---|
| `expirationDate` | date | The expiration date, in the instance's default time zone. |
| `expirationDateWithoutTime` | text | The same date without the time, in `yyyy-MM-dd` format. Use this field to display the date. |

```json
{
  "type": "DocumentExpired",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Services agreement",
    "expirationDate": "2026-09-30T00:00:00-03:00",
    "expirationDateWithoutTime": "2026-09-30"
  }
}
```

### DocumentDeleted

Signer sends this event when one or more documents are deleted. The event name is singular, but the event
carries a list of documents. In this event, `data` has only the `documents` list and the `action` field,
with no common fields outside the list.

| Field | Type | Description |
|---|---|---|
| `documents` | list | The deleted documents. Each item has the [common fields](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#common-fields-of-document-events). |
| `action` | text | What caused the deletion. See the values below. |

| `action` | Meaning |
|---|---|
| `DeletedByUserOrApplication` | A user or an application deleted the documents. |
| `DeletedByOrganization` | The organization made a bulk deletion. |
| `DeletedByFolder` | Someone deleted the folder that held the documents. |

> **Note**
>
> For `DeletedByOrganization` and `DeletedByFolder`, the `documents` list has at most 100 documents, even
> when the deletion affected more documents.

```json
{
  "type": "DocumentDeleted",
  "data": {
    "action": "DeletedByUserOrApplication",
    "documents": [
      { "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11", "name": "Contract 1" }
    ]
  }
}
```

## Billing event

### InvoiceClosed

Signer sends this event when an invoice is closed. The event does not use the organization's webhook. It
uses the instance billing webhook, which the system administrator configures. The `data` of this event does
not have the common fields of document events.

| Field | Type | Description |
|---|---|---|
| `id` | number | The invoice id. |
| `month` | number | The invoice month. |
| `year` | number | The invoice year. |
| `value` | number | The invoice amount. |
| `invoiceTotals` | list | The totals per transaction type. Each item has `transactionType`, `price`, `total`, `totalInTrialPeriod` and `value`. |
| `organization` | object | The invoice organization, with the same fields as `organization` in the [common fields](https://docs.lacunasoftware.com/en-us/articles/signer/webhook-events#common-fields-of-document-events). |
| `billingInformation` | object | The billing data of the organization, such as `contactName`, `email`, `phone` and the address. |
| `totalStorageUsed` | number | The total storage used, in bytes. |

The sample below does not show every field of `invoiceTotals` and `billingInformation`:

```json
{
  "type": "InvoiceClosed",
  "data": {
    "id": 1042,
    "month": 9,
    "year": 2026,
    "value": 480.00,
    "invoiceTotals": [
      { "transactionType": "Document", "total": 120, "totalInTrialPeriod": 0, "value": 240.00 },
      { "transactionType": "Signature", "total": 240, "totalInTrialPeriod": 0, "value": 240.00 }
    ],
    "organization": {
      "id": "5f2c9a71-3e8d-4a12-bb90-6d4e2f1c8a33",
      "name": "Acme Inc.",
      "identifier": "11222333000181",
      "owner": null
    },
    "billingInformation": {
      "contactName": "Acme Billing",
      "email": "billing@acme.com",
      "phone": "+55 61 3000-0000"
    },
    "totalStorageUsed": 734003200
  }
}
```

## See also

* [Webhooks](https://docs.lacunasoftware.com/en-us/articles/signer/webhooks)
* [Delivery, retries and ordering](https://docs.lacunasoftware.com/en-us/articles/signer/webhooks#delivery-retries-and-ordering)