Webhooks

Os webhooks avisam seu sistema quando um evento relevante ocorre. Eles reduzem polling, aceleram automações e devem ser tratados como notificações assíncronas.

Evento disponível

Evento	Quando é enviado
`ENVELOPE_COMPLETED`	Depois que todas as ações terminam e o envelope chega a `COMPLETED`

Cadastrar um endpoint

Você também pode listar os endpoints com GET /v4/api/webhooks/ e alterar um cadastro com PATCH /v4/api/webhooks/{webhookId}.

Requisitos da URL

A URL precisa:

usar HTTPS;

usar a porta 443;

apontar para um host público;

não conter credenciais;

não resolver para localhost, rede privada, link-local ou serviço de metadados.

A SuperSign revalida o DNS durante a conexão, não segue redirects e encerra a tentativa após 20 segundos.

Payload

{
  "id": "9d4fb916-5ab7-4a49-9014-1249345f1c6c",
  "event": "ENVELOPE_COMPLETED",
  "createdAt": "2026-09-03T18:30:00.000Z",
  "data": {
    "envelope": {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "COMPLETED",
      "completedAt": "2026-09-03T18:29:58.000Z"
    },
    "documents": [
      {
        "id": "2f1c5d8d-97dd-40a8-aefe-1eec9d17e301",
        "name": "contrato.pdf",
        "originalFileHash": "4f6f53d15ea7ed8cb002f85d2cb1f6c0f2bd5861d89fc3f9f30670ecf40cb3d2"
      }
    ],
    "signatories": [
      {
        "id": "7a9e6679-7425-40de-944b-e07fc1f90ae7",
        "name": "Pessoa Exemplo",
        "email": "pessoa@example.com",
        "phoneNumber": null,
        "signedAt": "2026-09-03T18:25:00.000Z"
      }
    ]
  }
}

Na Sandbox, o payload traz "environment": "sandbox" e a entrega leva o
header X-SuperSign-Environment: sandbox. Em Produção o campo e o header
são omitidos: o payload de produção continua exatamente como sempre foi,
para não quebrar receptor com validação estrita de schema.

Resposta e retentativas

Responda com qualquer status 2xx o mais rápido possível.

Grave o evento e processe o trabalho pesado de forma assíncrona.

Timeout, falha de rede ou resposta não 2xx provocam nova tentativa.

São feitas até 3 tentativas no total, com backoff exponencial iniciado em 5 segundos.

A ordem absoluta entre eventos não deve ser presumida.

Use o campo id do evento como chave de deduplicação. O mesmo evento pode ser entregue mais de uma vez.

Verificação segura

Nesta versão, o contrato público do webhook não inclui assinatura HMAC. Trate o webhook como um aviso e, antes de liberar dinheiro, acesso, documento ou outra ação irreversível, confirme o envelope pela rota autenticada:

Valide também event, formato dos IDs e estado esperado. Não exija environment — ele só existe na Sandbox. Nunca confie apenas em campos de contato recebidos no payload.

Privacidade e operação

O payload pode conter nome, e-mail e telefone de signatários; proteja logs e filas.

Não registre sua API Key nem URLs temporárias de download.

Monitore falhas e latência do endpoint.

Responda 2xx a eventos desconhecidos depois de registrá-los; isso evita retentativas infinitas quando novos eventos forem adicionados.

Mantenha o consumidor tolerante a novos campos.

Evento disponível#

Cadastrar um endpoint#

Requisitos da URL#

Payload#

Resposta e retentativas#

Verificação segura#