Webhooks

Os webhooks avisam seu sistema quando algo acontece com um envelope: ele foi
enviado, alguém assinou ou recusou, ele foi concluído, anulado ou expirou, ou um e-mail ao participante não foi entregue. Com eles você não
precisa consultar a API em laço para descobrir o que mudou. Trate cada aviso como
uma notificação assíncrona: chega logo depois do fato, mas pode chegar repetida
ou fora de ordem.

Webhooks fazem parte do plano com API: conta sem API não cria nem reativa endpoint (403 API_NOT_IN_PLAN) e não recebe entregas (ficam SKIPPED com errorType api_fora_do_plano).

Esta é a página de entrada. Cada evento tem a sua própria página, com o momento
exato em que dispara, o corpo completo de exemplo e a descrição de cada campo.

Páginas desta seção

Webhooks (esta página): eventos, cadastro e formato comum.

Evento ENVELOPE_SENT

Evento SIGNATORY_SIGNED

Evento ENVELOPE_COMPLETED

Evento ENVELOPE_VOIDED

Evento ENVELOPE_EXPIRED

Evento PARTICIPANT_DECLINED

Evento EMAIL_BOUNCED

Segurança e verificação

Entregas, retentativas e reenvio

Testar na Sandbox e automatizar

Eventos disponíveis

Evento	Quando é enviado	Página
`ENVELOPE_SENT`	Quando o envelope passa a circular. Também a cada reenvio depois de um ajuste, e quando o prazo de um envelope expirado é estendido e ele volta a circular.	ENVELOPE_SENT
`SIGNATORY_SIGNED`	Quando um signatário assina - um evento por assinatura. Também quando ele assina de novo depois de um ajuste. Aprovações não geram este evento.	SIGNATORY_SIGNED
`ENVELOPE_COMPLETED`	Depois que todas as ações terminam e o envelope chega a `COMPLETED`.	ENVELOPE_COMPLETED
`ENVELOPE_VOIDED`	Quando o envelope é anulado - por uma pessoa, pela API ou automaticamente pelo sistema (ex.: falha no envio). Anular de novo um envelope já anulado normalmente não gera outro evento; para deduplicar com segurança, use `event` + `data.envelope.id`.	ENVELOPE_VOIDED
`ENVELOPE_EXPIRED`	Quando o prazo do envelope vence sem que ele tenha sido concluído.	ENVELOPE_EXPIRED
`PARTICIPANT_DECLINED`	Quando um signatário ou aprovador recusa (pelo link ou, no caso do aprovador, pela API). O envelope passa a `DECLINED`. `participant.role` diz `SIGNATORY` ou `APPROVER`, e `reason` traz o motivo. Opcional: só chega a quem assinar o evento.	PARTICIPANT_DECLINED
`EMAIL_BOUNCED`	Quando um e-mail ao participante (convite, lembrete, código de verificação...) não é entregue. `failureType` diz `HARD`, `SOFT`, `SUPPRESSED` ou `OTHER`. No mesmo ciclo de envio só se repete se a falha piorar (temporária → definitiva); não muda o status do envelope e não cobre e-mail enviado por SMTP próprio da conta. Opcional: só chega a quem assinar o evento.	EMAIL_BOUNCED

Esses sete são todos os eventos que existem hoje. Novos tipos podem ser
adicionados no futuro e serão anunciados no Changelog; por isso
seu receptor deve responder 2xx a um evento que ainda não conhece (veja
Entregas, retentativas e reenvio).

Cada endpoint recebe só os eventos que assinou no campo events. Um endpoint
cadastrado só com ENVELOPE_COMPLETED continua recebendo só ele.

Um evento não encerra o ciclo do envelope. Um envelope que recebeu
ENVELOPE_EXPIRED pode voltar a circular (ENVELOPE_SENT) se o prazo for
estendido, e depois chegar a ENVELOPE_COMPLETED. Um envelope anulado ainda
como rascunho gera ENVELOPE_VOIDED sem nunca ter gerado ENVELOPE_SENT.

Uma sequência típica de um envelope com dois signatários:

ENVELOPE_SENT → SIGNATORY_SIGNED (1º) → SIGNATORY_SIGNED (2º) → ENVELOPE_COMPLETED

A ordem de chegada não é garantida: o ENVELOPE_COMPLETED pode chegar antes
do último SIGNATORY_SIGNED.

Cadastrar um endpoint

Escolha os eventos no campo events ao criar o endpoint:

A resposta 201 traz o signingSecret uma única vez. Ele não é guardado para replay de idempotência: se você repetir a criação com a mesma Idempotency-Key (por exemplo, depois de um timeout), nenhum endpoint novo é criado e a resposta é 409 IDEMPOTENCY_SECRET_NOT_REPLAYABLE, com o id do endpoint na mensagem. Nesse caso, obtenha um segredo válido em Girar o segredo de assinatura.

Cada conta pode ter até 20 endpoints de webhook (ativos e inativos). Ao passar disso, a criação responde 409 WEBHOOK_ENDPOINT_LIMIT_REACHED; exclua um endpoint que não usa mais e tente de novo.

Você também pode listar os endpoints com GET /v4/api/webhooks/ e alterar um
cadastro com PATCH /v4/api/webhooks/{webhookId} - por exemplo, para passar a
receber mais eventos:

Para parar de receber, exclua o endpoint com DELETE /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.

Endereço IPv6 literal que carrega um IPv4 (mapeado ::ffff:…, NAT64 64:ff9b::…, 6to4 2002:…) é avaliado pelo IPv4 embutido; faixas IPv6 não públicas (loopback, ::/96, unique local, link-local, multicast, documentação, Teredo) são recusadas.

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

Payload

Todo evento chega como um POST com corpo JSON, sempre com o mesmo formato
externo. O conteúdo de data depende do evento e está descrito na página de cada
um.

{
  "id": "c1b2a3d4-0000-4000-8000-000000000001",
  "event": "ENVELOPE_COMPLETED",
  "createdAt": "2026-09-13T14:00:02.000Z",
  "data": {}
}

Campo	Tipo	Descrição
`id`	string (UUID)	Identificador do evento. Use para deduplicar: o mesmo evento pode ser entregue mais de uma vez, e um reenvio manual mantém o mesmo `id`.
`event`	string	Um dos eventos da tabela acima.
`environment`	string	Só na Sandbox, com o valor `"sandbox"`. Em produção o campo não existe - não o exija.
`createdAt`	string (ISO 8601, UTC)	Quando a entrega foi montada. Para saber quando o fato aconteceu, use a data dentro de `data` (`occurredAt`, `signedAt` ou `completedAt`).
`data`	objeto	O conteúdo do evento (veja a página de cada evento).

Cabeçalhos recebidos

Cabeçalho	Quando aparece
`Content-Type`	`application/json`.
`X-SuperSign-Signature`	Quando o endpoint tem segredo de assinatura (todo endpoint cadastrado hoje tem). Veja Segurança e verificação.
`X-SuperSign-Environment`	Só na Sandbox, com o valor `sandbox`.

O payload pode conter nome, e-mail e telefone de participantes. Ele nunca
traz link de assinatura nem URL de download: para baixar documentos, use a API
autenticada.

Resposta e retentativas

Responda 2xx rápido e processe depois. As regras completas - quais respostas
geram nova tentativa, os intervalos e como deduplicar - estão em
Entregas, retentativas e reenvio.

Enviar evento de teste

Para validar o endpoint sem criar um envelope, POST /v4/api/webhooks/{webhookId}/test envia na hora um evento WEBHOOK_TEST assinado e devolve o que o seu servidor respondeu. Veja Enviar evento de teste.

Ver e reenviar entregas

Toda tentativa de disparo fica registrada e pode ser consultada e reenviada pela
API. Veja Entregas, retentativas e reenvio.

Girar o segredo de assinatura

Veja Segurança e verificação.

Verificação da assinatura (HMAC)

Veja Segurança e verificação.

Páginas desta seção#

Eventos disponíveis#

Cadastrar um endpoint#

Requisitos da URL#

Payload#

Cabeçalhos recebidos#

Resposta e retentativas#

Enviar evento de teste#

Ver e reenviar entregas#

Girar o segredo de assinatura#

Verificação da assinatura (HMAC)#