Evento PARTICIPANT_DECLINED

Um participante recusou o envelope. Vale para signatário e para
aprovador: o campo participant.role diz qual dos dois. Com a recusa, o
envelope passa ao status DECLINED e não pode mais ser assinado. Visão geral de
todos os eventos em Webhooks.

Este evento é opcional: só chega ao endpoint que incluir
PARTICIPANT_DECLINED no campo events. Endpoints já cadastrados não passam a
recebê-lo sozinhos.

Quando dispara

Quando um signatário recusa pelo link de assinatura.

Quando um aprovador recusa pelo link de aprovação.

Quando a integração recusa em nome de um aprovador com
POST /v4/api/envelopes/{envelopeId}/participants/{participantId}/decline.

Quando NÃO dispara

Recusa repetida do mesmo participante (clique duplo, duas abas, nova chamada):
a segunda recusa responde 409 PARTICIPANT_ALREADY_DECLINED e não gera
outro evento.

Anulação do envelope (por pessoa, API ou sistema): gera
ENVELOPE_VOIDED, não este evento.

Expiração por prazo: gera
ENVELOPE_EXPIRED.

Observadores não recusam.

Pode chegar mais de um PARTICIPANT_DECLINED para o mesmo envelope: se,
depois da primeira recusa, outro participante também recusar, chega outro
evento, com outro data.participant.id.

Exemplo de payload

Signatário:

{
  "id": "f1e2d3c4-0000-4000-8000-000000000030",
  "event": "PARTICIPANT_DECLINED",
  "createdAt": "2026-10-01T15:00:02.000Z",
  "data": {
    "envelope": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "DECLINED",
      "occurredAt": "2026-10-01T15:00:00.000Z"
    },
    "participant": {
      "id": "7a9e6679-7425-40de-944b-e07fc1f90ae7",
      "name": "Pessoa Exemplo",
      "email": "pessoa@example.com",
      "role": "SIGNATORY"
    },
    "reason": "O valor da cláusula 4 está diferente do combinado."
  }
}

Aprovador (pelo link ou pela API):

{
  "id": "f1e2d3c4-0000-4000-8000-000000000031",
  "event": "PARTICIPANT_DECLINED",
  "createdAt": "2026-10-01T16:00:02.000Z",
  "data": {
    "envelope": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "DECLINED",
      "occurredAt": "2026-10-01T16:00:00.000Z"
    },
    "participant": {
      "id": "0b1c2d3e-4f50-4a61-8b72-93a4b5c6d7e8",
      "name": "Aprovadora Exemplo",
      "email": "aprovadora@example.com",
      "role": "APPROVER"
    },
    "reason": "Falta o anexo de garantias."
  }
}

Campos de `data`

Campo	Tipo	Descrição
`envelope.id`	string (UUID)	Id do envelope.
`envelope.status`	string	Sempre `DECLINED`: o status que a recusa gravou.
`envelope.occurredAt`	string (ISO 8601, UTC)	Quando a recusa foi registrada.
`participant.id`	string (UUID)	Id do participante no envelope, o mesmo do `GET` da API.
`participant.name`	string ou `null`	Nome do participante no momento da recusa.
`participant.email`	string ou `null`	E-mail do participante no momento da recusa.
`participant.role`	string	`SIGNATORY` (signatário) ou `APPROVER` (aprovador).
`reason`	string ou `null`	O motivo informado, inteiro, como foi escrito. É texto livre de uma pessoa: trate como dado pessoal.

O corpo descreve a recusa no momento em que ela aconteceu: se o envelope for
ajustado depois, o evento não muda.

O formato externo (id, event, createdAt, environment) e os cabeçalhos
estão em Webhooks → Payload.

O que fazer com ele

Interromper o fluxo no seu sistema: o envelope não será concluído.

Mostrar o motivo a quem precisa agir (por exemplo, quem criou o envelope).

Para deduplicar, use data.envelope.id + data.participant.id: a mesma
recusa entregue de novo (retentativa ou reenvio) tem o mesmo par.

Não registre reason em log de aplicação: é texto livre e pode conter dados
pessoais.

Quando dispara#

Quando NÃO dispara#

Exemplo de payload#

Campos de data#

O que fazer com ele#

Quando dispara

Quando NÃO dispara

Exemplo de payload

Campos de `data`

O que fazer com ele