KivoSign
Webhooks

Eventos de webhook

Referência de todos os tipos de evento de webhook e seus payloads.

Estrutura do payload

Todos os eventos de webhook têm a mesma estrutura:

{
  "event": "DOCUMENT_COMPLETED",
  "payload": {
    // Dados do documento ou modelo, com os destinatários
  },
  "createdAt": "2024-04-22T11:52:18.277Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

Campos de primeiro nível

CampoTipoDescrição
eventstringIdentificador do evento (ex.: DOCUMENT_CREATED)
payloadobjectObjeto documento, com metadados e destinatários
createdAtdatetimeQuando o evento foi criado
webhookEndpointstringA URL que recebe este webhook

Campos do payload

CampoTipoDescrição
idnumberID numérico legado (v1) do documento ou modelo
envelopeIdstringIdentificador canônico da v2 (envelope_ + 16 caracteres)
externalIdstring?Identificador externo da integração
userIdnumberID do usuário dono
authOptionsobject?Opções de autenticação do documento
formValuesobject?Valores de formulário do PDF associados ao documento
titlestringTítulo do documento ou modelo
statusstringStatus atual: DRAFT, PENDING, COMPLETED, REJECTED, CANCELLED
visibilitystringVisibilidade do documento
createdAtdatetimeData/hora de criação do documento
updatedAtdatetimeData/hora da última alteração
completedAtdatetime?Data/hora da conclusão (quando todos assinaram)
deletedAtdatetime?Data/hora da exclusão
teamIdnumber?ID da equipe, se o documento pertencer a uma equipe
templateIdnumber?ID do modelo, se criado a partir de um modelo
sourcestringOrigem: DOCUMENT, TEMPLATE ou TEMPLATE_DIRECT_LINK
documentMetaobject?Metadados do documento, podem ser nulos (assunto, mensagem, opções de assinatura)
recipientsarrayLista de destinatários
RecipientarrayLista de destinatários (legado, igual a recipients)

Campos de metadados do documento

CampoTipoDescrição
idstringIdentificador do registro de metadados
subjectstring?Assunto do e-mail
messagestring?Corpo do e-mail
timezonestringFuso horário das datas
dateFormatstringFormato de data
redirectUrlstring?URL de redirecionamento após assinar
signingOrderstringPARALLEL or SEQUENTIAL
allowDictateNextSignerbooleanSe o signatário pode escolher o próximo
typedSignatureEnabledbooleanSe a assinatura digitada é permitida
uploadSignatureEnabledbooleanSe a assinatura por imagem é permitida
drawSignatureEnabledbooleanSe a assinatura desenhada é permitida
languagestringCódigo do idioma do documento
distributionMethodstringForma de distribuição do documento
emailSettingsobject?Configurações de e-mail deste documento

Campos do destinatário

CampoTipoDescrição
idnumberID do destinatário
envelopeIdstringID canônico do envelope
documentIdnumber?ID legado do documento; nulo em modelos
templateIdnumber?ID legado do modelo; nulo em documentos
emailstringE-mail do destinatário
namestringNome do destinatário
tokenstringToken único de assinatura
documentDeletedAtdatetime?Quando o destinatário ocultou o documento
expiresAtdatetime?Quando o link de assinatura expira
expirationNotifiedAtdatetime?Quando o aviso de expiração foi enviado
signedAtdatetime?Quando o destinatário assinou
authOptionsobject?Opções de autenticação do destinatário
rolestringPapel: SIGNER, VIEWER, APPROVER, ASSISTANT, CC
signingOrdernumber?Posição na ordem de assinatura
readStatusstringNOT_OPENED or OPENED
signingStatusstringNOT_SIGNED, SIGNED, or REJECTED
sendStatusstringNOT_SENT or SENT
rejectionReasonstring?Motivo, se o destinatário recusou

Use recipient.envelopeId como vínculo confiável com o envelope. Os campos legados documentId e templateId dependem do tipo do envelope, então um deles sempre vem nulo.

Eventos do ciclo de vida do documento

Estes eventos acompanham o documento ao longo do ciclo de vida.

document.created

Disparado quando um novo documento é criado.

Nome do evento: DOCUMENT_CREATED

{
  "event": "DOCUMENT_CREATED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "externalId": null,
    "userId": 1,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contrato.pdf",
    "status": "DRAFT",
    "createdAt": "2024-04-22T11:44:43.341Z",
    "updatedAt": "2024-04-22T11:44:43.341Z",
    "completedAt": null,
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "doc_meta_123",
      "subject": "Please sign this document",
      "message": "Hello, please review and sign this document.",
      "timezone": "Etc/UTC",
      "dateFormat": "yyyy-MM-dd hh:mm a",
      "redirectUrl": null,
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "NOT_SENT"
      }
    ],
    "Recipient": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "NOT_SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:44:44.779Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.sent

Disparado quando um documento é enviado aos destinatários para assinatura.

Nome do evento: DOCUMENT_SENT

O status do documento muda para PENDING e os destinatários passam a ter sendStatus: "SENT".

{
  "event": "DOCUMENT_SENT",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "externalId": null,
    "userId": 1,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contrato.pdf",
    "status": "PENDING",
    "createdAt": "2024-04-22T11:44:43.341Z",
    "updatedAt": "2024-04-22T11:48:07.569Z",
    "completedAt": null,
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "doc_meta_123",
      "subject": "Please sign this document",
      "message": "Hello, please review and sign this document.",
      "timezone": "Etc/UTC",
      "dateFormat": "yyyy-MM-dd hh:mm a",
      "redirectUrl": null,
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ],
    "Recipient": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": null,
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:48:07.945Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.opened

Disparado quando um destinatário abre o documento pela primeira vez.

Nome do evento: DOCUMENT_OPENED

O readStatus do destinatário muda para OPENED.

{
  "event": "DOCUMENT_OPENED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "status": "PENDING",
    "title": "contrato.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "readStatus": "OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:50:26.174Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.signed

Disparado quando um destinatário assina o documento. Dispara a cada assinatura, e não só quando o documento é concluído.

Nome do evento: DOCUMENT_SIGNED

O signingStatus do destinatário muda para SIGNED e signedAt é preenchido.

{
  "event": "DOCUMENT_SIGNED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "status": "COMPLETED",
    "title": "contrato.pdf",
    "source": "DOCUMENT",
    "completedAt": "2024-04-22T11:52:05.707Z",
    "recipients": [
      {
        "id": 51,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "signedAt": "2024-04-22T11:52:05.688Z",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:18.577Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.recipient.completed

Disparado quando um destinatário conclui a ação exigida (assinar, aprovar ou visualizar). Útil para acompanhar o progresso de cada destinatário em documentos com vários destinatários.

Nome do evento: DOCUMENT_RECIPIENT_COMPLETED

{
  "event": "DOCUMENT_RECIPIENT_COMPLETED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "status": "PENDING",
    "title": "contrato.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "signedAt": "2024-04-22T11:52:05.688Z",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:06.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.completed

Disparado quando todos os destinatários concluem as ações exigidas.

Nome do evento: DOCUMENT_COMPLETED

O status do documento muda para COMPLETED e completedAt é preenchido.

{
  "event": "DOCUMENT_COMPLETED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "externalId": null,
    "userId": 1,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contrato.pdf",
    "status": "COMPLETED",
    "createdAt": "2024-04-22T11:44:43.341Z",
    "updatedAt": "2024-04-22T11:52:05.708Z",
    "completedAt": "2024-04-22T11:52:05.707Z",
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "doc_meta_123",
      "subject": "Please sign this document",
      "message": "Hello, please review and sign this document.",
      "timezone": "Etc/UTC",
      "dateFormat": "yyyy-MM-dd hh:mm a",
      "redirectUrl": null,
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 50,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "revisor@exemplo.com",
        "name": "Maria Souza",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:51:10.055Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "VIEWER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      },
      {
        "id": 51,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "HkrptwS42ZBXdRKj1TyUo",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:52:05.688Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 2,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ],
    "Recipient": [
      {
        "id": 50,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "revisor@exemplo.com",
        "name": "Maria Souza",
        "token": "vbT8hi3jKQmrFP_LN1WcS",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:51:10.055Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "VIEWER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      },
      {
        "id": 51,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "HkrptwS42ZBXdRKj1TyUo",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": "2024-04-22T11:52:05.688Z",
        "authOptions": {
          "accessAuth": null,
          "actionAuth": null
        },
        "signingOrder": 2,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "OPENED",
        "signingStatus": "SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:18.277Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.rejected

Disparado quando um destinatário recusa o documento.

Nome do evento: DOCUMENT_REJECTED

O signingStatus do destinatário muda para REJECTED e rejectionReason traz o motivo.

{
  "event": "DOCUMENT_REJECTED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "status": "PENDING",
    "title": "contrato.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "signedAt": "2024-04-22T11:48:07.569Z",
        "rejectionReason": "I do not agree with the terms",
        "readStatus": "OPENED",
        "signingStatus": "REJECTED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:48:07.945Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.cancelled

Disparado quando um documento pendente é cancelado com POST /envelope/cancel, ou quando o dono ou um membro da equipe exclui um documento. Excluir um rascunho ou documento pendente o apaga de vez; excluir um documento concluído faz uma exclusão lógica.

Este evento não é disparado quando um destinatário oculta o documento da própria caixa de entrada.

Nome do evento: DOCUMENT_CANCELLED

{
  "event": "DOCUMENT_CANCELLED",
  "payload": {
    "id": 7,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "externalId": null,
    "userId": 3,
    "authOptions": null,
    "formValues": null,
    "visibility": "EVERYONE",
    "title": "contrato.pdf",
    "status": "PENDING",
    "createdAt": "2025-01-27T11:02:14.393Z",
    "updatedAt": "2025-01-27T11:03:16.387Z",
    "completedAt": null,
    "deletedAt": null,
    "teamId": null,
    "templateId": null,
    "source": "DOCUMENT",
    "documentMeta": {
      "id": "cm6exvn96006ji02rqvzjvwoy",
      "subject": "",
      "message": "",
      "timezone": "Etc/UTC",
      "dateFormat": "yyyy-MM-dd hh:mm a",
      "redirectUrl": "",
      "signingOrder": "PARALLEL",
      "allowDictateNextSigner": false,
      "typedSignatureEnabled": true,
      "uploadSignatureEnabled": true,
      "drawSignatureEnabled": true,
      "language": "en",
      "distributionMethod": "EMAIL",
      "emailSettings": null
    },
    "recipients": [
      {
        "id": 7,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 7,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "XkKx1HCs6Znm2UBJA2j6o",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": { "accessAuth": null, "actionAuth": null },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ],
    "Recipient": [
      {
        "id": 7,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 7,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "token": "XkKx1HCs6Znm2UBJA2j6o",
        "documentDeletedAt": null,
        "expiresAt": null,
        "expirationNotifiedAt": null,
        "signedAt": null,
        "authOptions": { "accessAuth": null, "actionAuth": null },
        "signingOrder": 1,
        "rejectionReason": null,
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2025-01-27T11:03:27.730Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

recipient.expired

Disparado quando o prazo de assinatura de um destinatário vence, em um documento pendente, antes que ele assine ou recuse.

Nome do evento: RECIPIENT_EXPIRED

O expiresAt do destinatário traz o prazo de assinatura, e expirationNotifiedAt é preenchido quando a expiração é processada.

{
  "event": "RECIPIENT_EXPIRED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "status": "PENDING",
    "title": "contrato.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "documentId": 10,
        "templateId": null,
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "expiresAt": "2024-04-22T11:51:00.000Z",
        "expirationNotifiedAt": "2024-04-22T11:52:00.000Z",
        "readStatus": "OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-22T11:52:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

document.reminder.sent

Disparado quando um lembrete é enviado a um destinatário que ainda não concluiu a ação.

Nome do evento: DOCUMENT_REMINDER_SENT

{
  "event": "DOCUMENT_REMINDER_SENT",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "status": "PENDING",
    "title": "contrato.pdf",
    "source": "DOCUMENT",
    "recipients": [
      {
        "id": 52,
        "envelopeId": "envelope_abcdefhiklmnorst",
        "email": "signatario@exemplo.com",
        "name": "João Silva",
        "role": "SIGNER",
        "readStatus": "NOT_OPENED",
        "signingStatus": "NOT_SIGNED",
        "sendStatus": "SENT"
      }
    ]
  },
  "createdAt": "2024-04-23T09:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

Eventos de modelo

Os eventos de modelo acompanham as mudanças nos modelos de documento reutilizáveis. O payload tem a mesma estrutura do payload de documento. Em TEMPLATE_CREATED, TEMPLATE_UPDATED e TEMPLATE_DELETED, o ID numérico legado do próprio modelo vem em id e templateId é null. Só o TEMPLATE_USED, cujo payload descreve o novo envelope de documento criado a partir do modelo, traz o ID legado do modelo de origem em templateId, com source igual a TEMPLATE.

template.created

Disparado quando um novo modelo é criado.

Nome do evento: TEMPLATE_CREATED

{
  "event": "TEMPLATE_CREATED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "title": "Meu modelo",
    "status": "DRAFT",
    "templateId": null,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T11:44:44.779Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

template.updated

Disparado quando as configurações, os destinatários ou os campos de um modelo são alterados.

Nome do evento: TEMPLATE_UPDATED

{
  "event": "TEMPLATE_UPDATED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "title": "Meu modelo atualizado",
    "status": "DRAFT",
    "templateId": null,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T12:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

template.deleted

Disparado quando um modelo é excluído.

Nome do evento: TEMPLATE_DELETED

{
  "event": "TEMPLATE_DELETED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "title": "Modelo excluído",
    "status": "DRAFT",
    "templateId": null,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T13:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

template.used

Disparado quando um documento é criado a partir de um modelo. Dispara junto com document.created e permite acompanhar especificamente o uso dos modelos.

Nome do evento: TEMPLATE_USED

{
  "event": "TEMPLATE_USED",
  "payload": {
    "id": 10,
    "envelopeId": "envelope_abcdefhiklmnorst",
    "title": "Documento a partir do modelo",
    "status": "DRAFT",
    "templateId": 10,
    "source": "TEMPLATE",
    "recipients": []
  },
  "createdAt": "2024-04-22T14:00:00.000Z",
  "webhookEndpoint": "https://your-endpoint.com/webhook"
}

Resumo dos eventos

Eventos de documento

EventoQuando disparaPrincipais mudanças
DOCUMENT_CREATEDDocumento enviado ou criado a partir de modelostatus: "DRAFT"
DOCUMENT_SENTDocumento enviado aos destinatáriosstatus: "PENDING", destinatários com sendStatus: "SENT"
DOCUMENT_OPENEDDestinatário abre o documento pela primeira vezDestinatário com readStatus: "OPENED"
DOCUMENT_SIGNEDDestinatário assina o documentoDestinatário com signingStatus: "SIGNED", signedAt preenchido
DOCUMENT_RECIPIENT_COMPLETEDDestinatário conclui a açãoDestinatário com signingStatus: "SIGNED", signedAt preenchido
DOCUMENT_COMPLETEDTodos os destinatários concluemstatus: "COMPLETED", completedAt preenchido
DOCUMENT_REJECTEDDestinatário recusa o documentoDestinatário com signingStatus: "REJECTED", rejectionReason preenchido
DOCUMENT_CANCELLEDDocumento pendente cancelado, ou documento excluídostatus: "CANCELLED" após o cancelamento; a exclusão pode apagar o documento ou fazer exclusão lógica
RECIPIENT_EXPIREDPrazo de assinatura do destinatário venceexpiresAt vencido, expirationNotifiedAt preenchido
DOCUMENT_REMINDER_SENTLembrete enviado ao destinatárioNenhuma mudança de status

Eventos de modelo

EventoQuando disparaPrincipais mudanças
TEMPLATE_CREATEDNovo modelo criadosource: "TEMPLATE"
TEMPLATE_UPDATEDConfigurações ou campos alteradossource: "TEMPLATE"
TEMPLATE_DELETEDModelo excluídosource: "TEMPLATE"
TEMPLATE_USEDDocumento criado a partir do modelosource: "TEMPLATE"

Tratando os eventos

Ao processar os eventos de webhook:

Verifique o segredo: confira se o cabeçalho X-Documenso-Secret é igual ao segredo configurado

Confira o tipo de evento: use o campo event para decidir a ação

Processe de forma idempotente: os webhooks podem ser reenviados, então trate eventos duplicados

Responda rápido: retorne um status 2xx em até 10 segundos

app.post('/webhook', (req, res) => {
  const secret = req.headers['x-documenso-secret'];

  if (secret !== process.env.WEBHOOK_SECRET) {
    return res.status(401).send('Unauthorized');
  }

  const { event, payload } = req.body;

  switch (event) {
    case 'DOCUMENT_COMPLETED':
      console.log(`Documento ${payload.id} concluído`);
      break;
    case 'DOCUMENT_RECIPIENT_COMPLETED':
      const signer = payload.recipients.find((r) => r.signingStatus === 'SIGNED');
      console.log(`${signer?.name} concluiu a ação no documento ${payload.id}`);
      break;
    case 'DOCUMENT_SIGNED':
      console.log(`Assinatura incluída no documento ${payload.id}`);
      break;
    case 'DOCUMENT_REJECTED':
      const rejecter = payload.recipients.find((r) => r.signingStatus === 'REJECTED');
      console.log(`${rejecter?.name} recusou: ${rejecter?.rejectionReason}`);
      break;
    case 'TEMPLATE_USED':
      console.log(`Modelo ${payload.templateId} usado para criar o documento ${payload.id}`);
      break;
  }

  res.status(200).send('OK');
});

Veja também

Configuração de webhooks

Configure webhooks para receber notificações em tempo real sobre eventos dos documentos.

Verificação de webhooks

Verifique a autenticidade dos webhooks recebidos.

Nesta página

Estrutura do payloadCampos de primeiro nívelCampos do payloadCampos de metadados do documentoCampos do destinatárioEventos do ciclo de vida do documentodocument.createddocument.sentdocument.openeddocument.signeddocument.recipient.completeddocument.completeddocument.rejecteddocument.cancelledrecipient.expireddocument.reminder.sentEventos de modelotemplate.createdtemplate.updatedtemplate.deletedtemplate.usedResumo dos eventosEventos de documentoEventos de modeloTratando os eventosVeja também