Eventos de Webhook

Lista completa de todos os eventos disponiveis com exemplos de payload.

Estrutura do payload

Todos os webhooks seguem a mesma estrutura base:

{
  "id": "evt_abc123def456",
  "event": "nome.do.evento",
  "timestamp": "2026-03-29T14:30:00Z",
  "data": {
    // conteudo especifico do evento
  }
}

Campo	Tipo	Descricao
id	string	Identificador unico do evento
event	string	Nome do evento
timestamp	string	Data/hora do evento (ISO 8601)
data	object	Dados especificos do evento

---

Eventos de Envelope

envelope.created

Disparado quando um novo envelope e criado.

{
  "id": "evt_env_created_001",
  "event": "envelope.created",
  "timestamp": "2026-03-29T14:30:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "name": "Contrato de Prestacao de Servicos",
    "status": "DRAFT",
    "createdBy": "usr_xyz789",
    "documentCount": 1,
    "signerCount": 2,
    "createdAt": "2026-03-29T14:30:00Z"
  }
}

envelope.sent

Disparado quando o envelope e enviado para os signatarios.

{
  "id": "evt_env_sent_001",
  "event": "envelope.sent",
  "timestamp": "2026-03-29T14:35:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "name": "Contrato de Prestacao de Servicos",
    "status": "PENDING",
    "sentBy": "usr_xyz789",
    "signerCount": 2,
    "expiresAt": "2026-04-28T14:35:00Z",
    "sentAt": "2026-03-29T14:35:00Z"
  }
}

envelope.completed

Disparado quando todos os signatarios assinaram o envelope.

{
  "id": "evt_env_completed_001",
  "event": "envelope.completed",
  "timestamp": "2026-03-29T16:00:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "name": "Contrato de Prestacao de Servicos",
    "status": "COMPLETED",
    "completedAt": "2026-03-29T16:00:00Z",
    "signers": [
      {
        "signerId": "sgn_001",
        "name": "Joao Silva",
        "email": "joao@exemplo.com",
        "signedAt": "2026-03-29T15:30:00Z"
      },
      {
        "signerId": "sgn_002",
        "name": "Maria Santos",
        "email": "maria@exemplo.com",
        "signedAt": "2026-03-29T16:00:00Z"
      }
    ],
    "downloadUrl": "https://api.tapsign.com.br/v1/envelopes/env_abc123/download"
  }
}

Envelope completo

Quando o envelope e completado, o campo downloadUrl permite baixar o documento assinado diretamente. O link e valido por 24 horas.

envelope.canceled

Disparado quando o envelope e cancelado pelo remetente.

{
  "id": "evt_env_canceled_001",
  "event": "envelope.canceled",
  "timestamp": "2026-03-29T17:00:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "name": "Contrato de Prestacao de Servicos",
    "status": "CANCELED",
    "canceledBy": "usr_xyz789",
    "reason": "Dados incorretos no contrato",
    "canceledAt": "2026-03-29T17:00:00Z"
  }
}

envelope.expired

Disparado quando o envelope expira sem todas as assinaturas.

{
  "id": "evt_env_expired_001",
  "event": "envelope.expired",
  "timestamp": "2026-04-28T14:35:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "name": "Contrato de Prestacao de Servicos",
    "status": "EXPIRED",
    "expiredAt": "2026-04-28T14:35:00Z",
    "signedCount": 1,
    "totalSigners": 2,
    "pendingSigners": [
      {
        "signerId": "sgn_002",
        "name": "Maria Santos",
        "email": "maria@exemplo.com"
      }
    ]
  }
}

---

Eventos de Signatario

signer.notified

Disparado quando o signatario recebe a notificacao para assinar.

{
  "id": "evt_sgn_notified_001",
  "event": "signer.notified",
  "timestamp": "2026-03-29T14:36:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "signerId": "sgn_001",
    "name": "Joao Silva",
    "email": "joao@exemplo.com",
    "notificationChannel": "EMAIL",
    "notifiedAt": "2026-03-29T14:36:00Z"
  }
}

signer.viewed

Disparado quando o signatario abre e visualiza o documento.

{
  "id": "evt_sgn_viewed_001",
  "event": "signer.viewed",
  "timestamp": "2026-03-29T15:00:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "signerId": "sgn_001",
    "name": "Joao Silva",
    "email": "joao@exemplo.com",
    "viewedAt": "2026-03-29T15:00:00Z",
    "ipAddress": "189.44.120.55",
    "userAgent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64)"
  }
}

signer.signed

Disparado quando o signatario assina o documento.

{
  "id": "evt_sgn_signed_001",
  "event": "signer.signed",
  "timestamp": "2026-03-29T15:30:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "signerId": "sgn_001",
    "name": "Joao Silva",
    "email": "joao@exemplo.com",
    "signatureType": "ELECTRONIC",
    "signedAt": "2026-03-29T15:30:00Z",
    "ipAddress": "189.44.120.55",
    "remainingSigners": 1,
    "totalSigners": 2
  }
}

signer.declined

Disparado quando o signatario recusa assinar o documento.

{
  "id": "evt_sgn_declined_001",
  "event": "signer.declined",
  "timestamp": "2026-03-29T15:30:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "signerId": "sgn_002",
    "name": "Maria Santos",
    "email": "maria@exemplo.com",
    "reason": "Nao concordo com os termos apresentados",
    "declinedAt": "2026-03-29T15:30:00Z"
  }
}

Envelope cancelado automaticamente

Quando um signatario recusa, o envelope e automaticamente cancelado. Voce tambem recebera o evento envelope.canceled em seguida.

---

Eventos de Documento

document.uploaded

Disparado quando um documento e adicionado a um envelope.

{
  "id": "evt_doc_uploaded_001",
  "event": "document.uploaded",
  "timestamp": "2026-03-29T14:29:00Z",
  "data": {
    "envelopeId": "env_abc123",
    "documentId": "doc_def456",
    "fileName": "contrato-servicos.pdf",
    "fileSize": 245780,
    "mimeType": "application/pdf",
    "pageCount": 5,
    "uploadedAt": "2026-03-29T14:29:00Z"
  }
}