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.

Request format

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

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

Field	Type	Description
`type`	text	The event type. See the list in 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`	One or more documents were created.
`DocumentSigned`	A participant signed the document.
`DocumentApproved`	A participant approved the document.
`DocumentRefused`	A participant refused the document.
`DocumentConcluded`	The flow finished: every action was completed.
`DocumentCanceled`	The document was canceled.
`DocumentPaused`	The document was paused.
`DocumentResumed`	A paused document was resumed.
`DocumentExpired`	The document reached its expiration date without being concluded.
`DocumentDeleted`	One or more documents were deleted.
`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`.

{
  "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.

{
  "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.

{
  "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.

{
  "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. Here, `flowActionId` can be `null`.

{
  "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.

{
  "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.
`reason`	text	The cancellation reason.

{
  "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.
`reason`	text	The reason given when pausing.

{
  "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.

{
  "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.

{
  "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.
`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.

{
  "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.
`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:

{
  "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
  }
}

Request format​

Events​

Common fields of document events​

Who acted​

Document events​

DocumentsCreated​

DocumentSigned​

DocumentApproved​

DocumentRefused​

DocumentConcluded​

DocumentCanceled​

DocumentPaused​

DocumentResumed​

DocumentExpired​

DocumentDeleted​

Billing event​

InvoiceClosed​

See also​