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.

Formato da requisição

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

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

Campo	Tipo	Descrição
`type`	texto	O tipo do evento. Veja a lista em 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`	Um ou mais documentos foram criados.
`DocumentSigned`	Um participante assinou o documento.
`DocumentApproved`	Um participante aprovou o documento.
`DocumentRefused`	Um participante recusou o documento.
`DocumentConcluded`	O fluxo terminou: todas as ações foram concluídas.
`DocumentCanceled`	O documento foi cancelado.
`DocumentPaused`	O documento foi pausado.
`DocumentResumed`	O documento pausado foi retomado.
`DocumentExpired`	O documento chegou à data de expiração sem ser concluído.
`DocumentDeleted`	Um ou mais documentos foram excluídos.
`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`.

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

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

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

{
  "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. Aqui, o `flowActionId` pode ser `null`.

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

{
  "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.
`reason`	texto	O motivo do cancelamento.

{
  "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.
`reason`	texto	O motivo informado ao pausar.

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

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

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

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

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

Ver em Markdown

Formato da requisição​

Eventos​

Campos comuns dos eventos de documento​

Quem fez a ação​

Eventos de documento​

DocumentsCreated​

DocumentSigned​

DocumentApproved​

DocumentRefused​

DocumentConcluded​

DocumentCanceled​

DocumentPaused​

DocumentResumed​

DocumentExpired​

DocumentDeleted​

Evento de faturamento​

InvoiceClosed​

Veja também​