---
title: "Referência dos eventos"
description: "Referência dos eventos de webhook do Signer: formato do corpo, campos de cada evento, tipos dos campos e um exemplo de cada evento."
canonical: "https://docs.lacunasoftware.com/articles/signer/webhook-events"
locale: "pt-BR"
product: "Signer"
last_updated: "2026-10-22"
---

# Referência dos eventos

O Signer envia um evento para a URL do webhook quando algo acontece com um documento, como uma assinatura
ou a conclusão do fluxo. Cada evento traz o tipo do evento e os dados do documento. Para cadastrar o
webhook e criar o endpoint que recebe os eventos, veja [Webhooks](https://docs.lacunasoftware.com/articles/signer/webhooks).

## Formato da requisição

O Signer envia um `POST` com `Content-Type: application/json` (UTF-8). O corpo tem sempre dois campos:

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

| Campo | Tipo | Descrição |
|---|---|---|
| `type` | texto | O tipo do evento. Veja a lista em [Eventos](https://docs.lacunasoftware.com/articles/signer/webhook-events#eventos). |
| `data` | objeto | Os dados do evento. O conteúdo muda conforme o `type`. |

O corpo segue estas convenções:

* Os nomes dos campos usam *camelCase*, como `creationDate`.
* Os valores de enumerações vêm como texto. Por exemplo, o Signer envia `"DocumentConcluded"`, e não `1`.
* As datas usam o formato ISO 8601, com o fuso horário, como `2026-09-10T14:27:35.115Z`.
* Os ids, como `id`, `userId` e `flowActionId`, são GUIDs em texto.

Nas tabelas desta página, um campo que pode vir como `null` tem "ou `null`" na coluna "Tipo".

## Eventos

| `type` | Quando o Signer envia |
|---|---|
| [`DocumentsCreated`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentscreated) | Um ou mais documentos foram criados. |
| [`DocumentSigned`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentsigned) | Um participante assinou o documento. |
| [`DocumentApproved`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentapproved) | Um participante aprovou o documento. |
| [`DocumentRefused`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentrefused) | Um participante recusou o documento. |
| [`DocumentConcluded`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentconcluded) | O fluxo terminou: todas as ações foram concluídas. |
| [`DocumentCanceled`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentcanceled) | O documento foi cancelado. |
| [`DocumentPaused`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentpaused) | O documento foi pausado. |
| [`DocumentResumed`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentresumed) | O documento pausado foi retomado. |
| [`DocumentExpired`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentexpired) | O documento chegou à data de expiração sem ser concluído. |
| [`DocumentDeleted`](https://docs.lacunasoftware.com/articles/signer/webhook-events#documentdeleted) | Um ou mais documentos foram excluídos. |
| [`InvoiceClosed`](https://docs.lacunasoftware.com/articles/signer/webhook-events#invoiceclosed) | Uma fatura foi fechada. |

## Campos comuns dos eventos de documento

Todo evento de documento traz em `data` os campos abaixo. Nos eventos `DocumentsCreated` e
`DocumentDeleted`, cada item da lista `documents` traz esses campos.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto (GUID) | O id do documento. |
| `name` | texto | O nome do documento. |
| `creationDate` | data | A data de criação do documento. |
| `updateDate` | data | A data da última alteração do documento. |
| `folder` | objeto ou `null` | A pasta do documento. É `null` quando o documento não está em uma pasta. |
| `folder.id` | texto (GUID) | O id da pasta. |
| `folder.name` | texto | O nome da pasta. |
| `folder.parentId` | texto (GUID) ou `null` | O id da pasta acima desta. É `null` quando a pasta não está dentro de outra pasta. |
| `folder.organizationName` | texto | O nome da organização da pasta. |
| `organization` | objeto ou `null` | A organização do documento. É `null` em documentos pessoais. |
| `organization.id` | texto (GUID) | O id da organização. |
| `organization.name` | texto | O nome da organização. |
| `organization.identifier` | texto | O CNPJ da organização. |
| `organization.owner` | objeto ou `null` | O dono de uma organização pessoal, com `id` e `name`. É `null` nas outras organizações. |
| `createdBy` | objeto | O usuário ou a aplicação que criou o documento, com `id` e `name`. |

```json
{
  "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
  "name": "Contrato de prestação de serviços",
  "creationDate": "2026-09-10T13:02:11.482Z",
  "updateDate": "2026-09-10T14:27:35.115Z",
  "folder": {
    "id": "0a9e1f3c-2b44-4f6a-9d0e-77c1b8a4e510",
    "name": "Contratos 2026",
    "parentId": null,
    "organizationName": "Acme S.A."
  },
  "organization": {
    "id": "5f2c9a71-3e8d-4a12-bb90-6d4e2f1c8a33",
    "name": "Acme S.A.",
    "identifier": "11222333000181",
    "owner": null
  },
  "createdBy": {
    "id": "4d961566-9b03-450c-b144-930e0294bac2",
    "name": "Integração ERP"
  }
}
```

Para ficarem curtos, os exemplos das seções abaixo mostram só `id` e `name` dos campos comuns.

## Quem fez a ação

Os eventos usam dois objetos para dizer quem fez a ação.

O objeto de participante aparece em `signature`, `approval` e `refusal`:

| Campo | Tipo | Descrição |
|---|---|---|
| `flowActionId` | texto (GUID) | O id da ação do fluxo, por exemplo a etapa de assinatura do participante. No `refusal`, pode ser `null`. |
| `date` | data | A data da ação. |
| `userId` | texto (GUID) | O id do usuário que fez a ação. |
| `name` | texto | O nome do usuário. |
| `identifier` | texto | O identificador do usuário, por exemplo o CPF. |
| `emailAddress` | texto | O e-mail do usuário. |
| `reason` | texto | O motivo da recusa. Só existe no `refusal`. |

O objeto de agente aparece em `canceledBy`, `pausedBy` e `resumedBy`. Um agente é um usuário ou uma
aplicação:

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | texto (GUID) | O id do usuário ou da aplicação. |
| `name` | texto | O nome do usuário ou da aplicação. |
| `type` | texto | `User` para um usuário, ou `Application` para uma aplicação. |

## Eventos de documento

### DocumentsCreated

O Signer envia este evento quando um ou mais documentos são criados. Um evento pode trazer vários
documentos. Neste evento, `data` tem só a lista `documents`, sem os campos comuns fora dela.

| Campo | Tipo | Descrição |
|---|---|---|
| `documents` | lista | Os documentos criados. Cada item tem os [campos comuns](https://docs.lacunasoftware.com/articles/signer/webhook-events#campos-comuns-dos-eventos-de-documento). |

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

### DocumentSigned

O Signer envia este evento quando um participante assina o documento. Se o documento tem vários
signatários, o Signer envia um evento para cada assinatura.

| Campo | Tipo | Descrição |
|---|---|---|
| `signature` | objeto | O participante que assinou. Veja o [objeto de participante](https://docs.lacunasoftware.com/articles/signer/webhook-events#quem-fez-a-ação). |

```json
{
  "type": "DocumentSigned",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "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

O Signer envia este evento quando um participante aprova o documento.

| Campo | Tipo | Descrição |
|---|---|---|
| `approval` | objeto | O participante que aprovou. Veja o [objeto de participante](https://docs.lacunasoftware.com/articles/signer/webhook-events#quem-fez-a-ação). |

```json
{
  "type": "DocumentApproved",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "approval": {
      "flowActionId": "7d2e9b41-0c6a-4f18-a3b5-92e1c4d7f630",
      "date": "2026-09-10T13:45:20.310Z",
      "userId": "2f7b4c18-6e9d-4a35-8b02-c1d6e9a3f574",
      "name": "Maria Souza",
      "identifier": "52998224725",
      "emailAddress": "maria.souza@mailinator.com"
    }
  }
}
```

### DocumentRefused

O Signer envia este evento quando um participante recusa o documento.

| Campo | Tipo | Descrição |
|---|---|---|
| `refusal` | objeto | O participante que recusou, com o campo `reason`. Veja o [objeto de participante](https://docs.lacunasoftware.com/articles/signer/webhook-events#quem-fez-a-ação). Aqui, o `flowActionId` pode ser `null`. |

```json
{
  "type": "DocumentRefused",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "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": "Valor divergente na cláusula 4"
    }
  }
}
```

### DocumentConcluded

O Signer envia este evento quando o fluxo termina, isto é, quando todas as ações do documento foram
concluídas. O evento traz só os [campos comuns](https://docs.lacunasoftware.com/articles/signer/webhook-events#campos-comuns-dos-eventos-de-documento).

```json
{
  "type": "DocumentConcluded",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços"
  }
}
```

### DocumentCanceled

O Signer envia este evento quando um usuário ou uma aplicação cancela o documento.

| Campo | Tipo | Descrição |
|---|---|---|
| `canceledBy` | objeto | Quem cancelou. Veja o [objeto de agente](https://docs.lacunasoftware.com/articles/signer/webhook-events#quem-fez-a-ação). |
| `reason` | texto | O motivo do cancelamento. |

```json
{
  "type": "DocumentCanceled",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "canceledBy": {
      "id": "4d961566-9b03-450c-b144-930e0294bac2",
      "name": "Integração ERP",
      "type": "Application"
    },
    "reason": "Contrato substituído por nova versão"
  }
}
```

### DocumentPaused

O Signer envia este evento quando um usuário pausa o documento. O evento existe a partir da versão 3.0.0
do Signer.

| Campo | Tipo | Descrição |
|---|---|---|
| `pausedBy` | objeto | Quem pausou. Veja o [objeto de agente](https://docs.lacunasoftware.com/articles/signer/webhook-events#quem-fez-a-ação). |
| `reason` | texto | O motivo informado ao pausar. |

```json
{
  "type": "DocumentPaused",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "pausedBy": {
      "id": "2f7b4c18-6e9d-4a35-8b02-c1d6e9a3f574",
      "name": "Maria Souza",
      "type": "User"
    },
    "reason": "Aguardando revisão do jurídico"
  }
}
```

### DocumentResumed

O Signer envia este evento quando um usuário retoma um documento pausado. O evento existe a partir da
versão 3.0.0 do Signer.

| Campo | Tipo | Descrição |
|---|---|---|
| `resumedBy` | objeto | Quem retomou. Veja o [objeto de agente](https://docs.lacunasoftware.com/articles/signer/webhook-events#quem-fez-a-ação). |

```json
{
  "type": "DocumentResumed",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "resumedBy": {
      "id": "2f7b4c18-6e9d-4a35-8b02-c1d6e9a3f574",
      "name": "Maria Souza",
      "type": "User"
    }
  }
}
```

### DocumentExpired

O Signer envia este evento quando o documento chega à data de expiração e o fluxo ainda não terminou.

| Campo | Tipo | Descrição |
|---|---|---|
| `expirationDate` | data | A data de expiração, no fuso horário padrão da instância. |
| `expirationDateWithoutTime` | texto | A mesma data sem a hora, no formato `yyyy-MM-dd`. Use este campo para exibir a data na tela. |

```json
{
  "type": "DocumentExpired",
  "data": {
    "id": "b12cb1b2-5d6e-40b2-a050-097d068c4c11",
    "name": "Contrato de prestação de serviços",
    "expirationDate": "2026-09-30T00:00:00-03:00",
    "expirationDateWithoutTime": "2026-09-30"
  }
}
```

### DocumentDeleted

O Signer envia este evento quando um ou mais documentos são excluídos. O nome do evento está no singular,
mas o evento traz uma lista de documentos. Neste evento, `data` tem só a lista `documents` e o campo
`action`, sem os campos comuns fora da lista.

| Campo | Tipo | Descrição |
|---|---|---|
| `documents` | lista | Os documentos excluídos. Cada item tem os [campos comuns](https://docs.lacunasoftware.com/articles/signer/webhook-events#campos-comuns-dos-eventos-de-documento). |
| `action` | texto | O que causou a exclusão. Veja os valores abaixo. |

| `action` | Significado |
|---|---|
| `DeletedByUserOrApplication` | Um usuário ou uma aplicação excluiu os documentos. |
| `DeletedByOrganization` | A organização fez uma exclusão em massa. |
| `DeletedByFolder` | Alguém excluiu a pasta que continha os documentos. |

> **Observação**
>
> Em `DeletedByOrganization` e `DeletedByFolder`, a lista `documents` traz no máximo 100 documentos, mesmo
> quando a exclusão afetou mais documentos.

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

## Evento de faturamento

### InvoiceClosed

O Signer envia este evento quando uma fatura é fechada. O evento não usa o webhook da organização. Ele
usa o webhook de faturamento da instância, que o administrador do sistema configura. O `data` deste evento
não tem os campos comuns dos eventos de documento.

| Campo | Tipo | Descrição |
|---|---|---|
| `id` | número | O id da fatura. |
| `month` | número | O mês da fatura. |
| `year` | número | O ano da fatura. |
| `value` | número | O valor da fatura. |
| `invoiceTotals` | lista | Os totais por tipo de transação. Cada item tem `transactionType`, `price`, `total`, `totalInTrialPeriod` e `value`. |
| `organization` | objeto | A organização da fatura, com os mesmos campos de `organization` dos [campos comuns](https://docs.lacunasoftware.com/articles/signer/webhook-events#campos-comuns-dos-eventos-de-documento). |
| `billingInformation` | objeto | Os dados de faturamento da organização, como `contactName`, `email`, `phone` e o endereço. |
| `totalStorageUsed` | número | O armazenamento total usado, em bytes. |

O exemplo abaixo não mostra todos os campos de `invoiceTotals` e de `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 S.A.",
      "identifier": "11222333000181",
      "owner": null
    },
    "billingInformation": {
      "contactName": "Financeiro Acme",
      "email": "financeiro@acme.com.br",
      "phone": "+55 61 3000-0000"
    },
    "totalStorageUsed": 734003200
  }
}
```

## Veja também

* [Webhooks](https://docs.lacunasoftware.com/articles/signer/webhooks)
* [Entrega, retentativas e ordem](https://docs.lacunasoftware.com/articles/signer/webhooks#entrega-retentativas-e-ordem)