Eventos de Webhook

Todos os eventos usam o mesmo payload JSON, em formato de compatibilidade: campos em snake_case e status em minúsculas. De um evento para outro mudam o event_type, o status e alguns campos extras.

Estrutura do payload

{
  "event_type": "doc_completed",
  "token": "3f6c1a52-8d0e-4b8a-9c61-2f7d5e4a1b90",
  "external_id": "pedido-42",
  "status": "completed",
  "signers": [
    {
      "name": "Maria Silva",
      "email": "[email protected]",
      "status": "signed",
      "sign_url": "",
      "phone_country": "",
      "phone_number": "+5511987654321",
      "times_viewed": 0,
      "last_view_at": null
    }
  ],
  "signed_file": "https://...",
  "notification_type": null,
  "days_to_expire": null
}

Campo	Tipo	Descrição
event_type	string	Nome do evento
token	string (UUID)	Identificador público do envelope. É o mesmo token devolvido ao criar documento via modelo
external_id	string ou null	Seu identificador, quando o documento foi criado com externalId. null nos demais casos
status	string	Status do envelope no momento do envio: draft, sent, in_progress, completed, canceled ou expired
signers	array	Todos os signatários do envelope
signers[].name	string	Nome do signatário
signers[].email	string	E-mail do signatário
signers[].status	string	pending, notified, viewed, signed ou declined
signers[].phone_number	string	Telefone cadastrado no signatário, ou "" quando não há
signers[].sign_url, signers[].phone_country	string	Mantidos por compatibilidade. Hoje vêm sempre ""
signers[].times_viewed, signers[].last_view_at	number, null	Mantidos por compatibilidade. Hoje vêm sempre 0 e null
signer_who_signed	object	Signatário que gerou o evento (name, email, status). Presente em doc_viewed, doc_refused e doc_signed
rejected_reason	string	Motivo informado na recusa. Só em doc_refused
signed_file	string	URL temporária do PDF assinado, válida por 24 horas. Só em doc_signed e doc_completed
notification_type, days_to_expire	null	Mantidos por compatibilidade. Hoje vêm sempre null

signer_who_signed.status vem sempre signed

Por compatibilidade, o status dentro de signer_who_signed é fixo em signed, inclusive em doc_viewed e doc_refused. Para saber o que aconteceu, use o event_type e o status do signatário dentro de signers.

Como relacionar o evento com o seu sistema

O payload não traz o id numérico do envelope. Use o external_id (quando o documento foi criado com externalId) ou o token. Os logs de entrega mostram o envelopeId numérico de cada entrega.

---

doc_viewed

Disparado quando um signatário abre o link de assinatura. Cada abertura feita antes de o signatário assinar ou recusar gera um novo evento, então o mesmo signatário pode aparecer mais de uma vez.

{
  "event_type": "doc_viewed",
  "token": "3f6c1a52-8d0e-4b8a-9c61-2f7d5e4a1b90",
  "external_id": "pedido-42",
  "status": "in_progress",
  "signers": [
    {
      "name": "Maria Silva",
      "email": "[email protected]",
      "status": "viewed",
      "sign_url": "",
      "phone_country": "",
      "phone_number": "",
      "times_viewed": 0,
      "last_view_at": null
    }
  ],
  "signer_who_signed": {
    "name": "Maria Silva",
    "email": "[email protected]",
    "status": "signed"
  },
  "notification_type": null,
  "days_to_expire": null
}

---

doc_signed

Disparado quando o último signatário assina, depois que o PDF assinado é gerado. Traz o mesmo conteúdo do doc_completed e mais o signer_who_signed, com quem concluiu o envelope.

observação

Se a geração do PDF assinado for refeita automaticamente pelo TapSign depois de uma falha, o signer_who_signed pode vir com name e email nulos.

---

doc_refused

Disparado quando um signatário recusa assinar. A recusa não altera o status do envelope: o campo status continua com o valor que o envelope tinha (por exemplo in_progress).

{
  "event_type": "doc_refused",
  "token": "3f6c1a52-8d0e-4b8a-9c61-2f7d5e4a1b90",
  "external_id": "pedido-42",
  "status": "in_progress",
  "signers": [
    {
      "name": "Maria Silva",
      "email": "[email protected]",
      "status": "declined",
      "sign_url": "",
      "phone_country": "",
      "phone_number": "",
      "times_viewed": 0,
      "last_view_at": null
    }
  ],
  "signer_who_signed": {
    "name": "Maria Silva",
    "email": "[email protected]",
    "status": "signed"
  },
  "rejected_reason": "Os valores não conferem com a proposta.",
  "notification_type": null,
  "days_to_expire": null
}

---

doc_completed

Disparado quando todos os signatários assinaram e o PDF assinado ficou pronto. O status vem completed e o signed_file traz o link do PDF assinado (veja o exemplo em Estrutura do payload).

Baixe o PDF assim que receber

O signed_file expira em 24 horas. Baixe o arquivo e guarde no seu lado. Retentativas e reenvios manuais mandam o payload original, então um reenvio feito muito tempo depois pode trazer um link já expirado. Nesse caso, gere um link novo pela rota de download do PDF.

---

doc_canceled

Disparado quando o envelope é cancelado, seja pela rota de cancelamento de envelope, pelo cancelamento por token da API de integração ou pelo cancelamento de um pacote (um evento por envelope do pacote). Payload base, com status igual a canceled.

---

doc_expired

Disparado quando o prazo do envelope vence sem conclusão. Payload base, com status igual a expired.

A verificação de prazos roda uma vez por hora, então o evento pode chegar até cerca de uma hora depois do vencimento.