Entregas, retentativas e reenvio

O que acontece depois que o evento sai: como responder, quando a SuperSign tenta de novo, e como consultar e reenviar entregas pela API. Visão geral em Webhooks.

Resposta e retentativas

Responda com qualquer status 2xx rapidamente, somente após aceitação durável.

Grave evento e pendência atomicamente; processe o trabalho pesado com worker
capaz de retomar pendências após falhas e reinícios. Uma linha já existente
não prova conclusão ou retomada. Veja o contrato local da inbox e do worker.

Timeout, falha de rede ou TLS, 403, 404, 408, 425, 429 e qualquer 5xx provocam nova tentativa.

403 e 404 são retentados de propósito, ainda que pareçam recusa definitiva:

403 é a outra face do limite de taxa. Cloudflare com ação Block e o AWS WAF devolvem 403 - e não 429 - quando uma rajada estoura a regra, e a rajada é real: um lote de assinaturas fechando dispara vários ENVELOPE_COMPLETED em sequência para o mesmo endpoint.

404 costuma ser o rollout do próprio receptor: o nginx-ingress devolve o 404 do default backend enquanto o Ingress é recriado num helm upgrade, e Vercel/Cloudflare devolvem 404 DEPLOYMENT_NOT_FOUND durante o deploy. Tratar isso como permanente perderia o evento para sempre.

Redirecionamentos (3xx) e os demais 4xx não são retentados: são tratados como recusa definitiva do endpoint. Corrija a URL ou o receptor e o próximo evento volta a ser entregue. Em particular, 401 (credencial errada no cadastro) e 410 (Gone, o receptor removeu o endpoint de propósito) são permanentes: insistir por horas não muda o resultado.

São feitas até 6 tentativas no total: a primeira imediata e mais 5 com esperas fixas de 10 segundos, 1 minuto, 10 minutos, 1 hora e 6 horas (janela total de ~7 horas).

A ordem absoluta entre eventos não deve ser presumida - e, por causa da janela acima, um evento pode chegar horas depois do fato.

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

Tabela de tentativas

Tentativa	Espera desde a anterior	Tempo aproximado desde o evento
1ª	imediata	0
2ª	10 segundos	~10 s
3ª	1 minuto	~1 min
4ª	10 minutos	~11 min
5ª	1 hora	~1 h 11 min
6ª	6 horas	~7 h 11 min

Se a 6ª tentativa também falhar, a entrega fica FAILED e pode ser reenviada
manualmente (veja abaixo).

Status de uma entrega

Status	Significado
`PENDING`	Em curso: aguardando a primeira tentativa ou uma retentativa.
`DELIVERED`	Seu endpoint respondeu `2xx`.
`FAILED`	As tentativas se esgotaram ou o endpoint deu uma recusa definitiva. Pode reenviar.
`SKIPPED`	Não enviada: o endpoint estava desativado ou tinha sido excluído no momento do disparo. Reative o endpoint antes de reenviar; com ele desativado ou excluído, o reenvio responde `409`. Entregas de conta suspensa (exceto por pagamento pendente) também ficam `SKIPPED`, com `errorType` `conta_suspensa`, e podem ser reenviadas depois da reativação. Conta sem API no plano também fica `SKIPPED`, com `errorType` `api_fora_do_plano`.

Idempotência e ordem

Deduplique pelo id do evento: o mesmo evento pode chegar mais de uma vez, e
um reenvio manual mantém o mesmo id.

Não dependa da ordem de chegada: um ENVELOPE_COMPLETED pode chegar antes do
último SIGNATORY_SIGNED, e uma retentativa pode chegar horas depois de um
evento mais novo. Para saber o estado atual, consulte
GET /v4/api/envelopes/{envelopeId}.

Desativação automática por falhas seguidas

Para não ficar tentando um endereço que não responde, a SuperSign® desativa
sozinha o webhook que falha por vários dias. A conta é avisada antes por
e-mail, com tempo de corrigir.

Contagem: cada entrega que termina FAILED soma uma falha seguida. Uma
entrega DELIVERED zera a contagem. Entrega SKIPPED (conta suspensa, conta
sem API, endpoint desativado) não conta e não zera.

Evento de teste: o evento de teste não soma falha nem zera a contagem.

Aviso prévio: com o webhook falhando há 1 dia e com 3 ou mais entregas FAILED seguidas, o dono da conta recebe
um e-mail (uma vez por sequência de falhas). O e-mail mostra só o host do
endereço, nunca a URL inteira.

Desativação: com o webhook falhando há 3 dias ou mais e com 20 ou
mais entregas FAILED seguidas (as duas condições juntas), o webhook passa
a isActive: false e a conta recebe um segundo e-mail.

Como saber: na resposta de webhook (GET /v4/api/webhooks,
PATCH /v4/api/webhooks/{webhookId}), disabledAt traz o momento da
desativação e disabledReason traz o motivo: falhas_consecutivas quando foi
a plataforma, ou manual quando foi você (isActive: false). Os dois são
null num webhook nunca desativado, ou desativado antes de esse registro
existir.

Última falha: GET /v4/api/webhooks devolve lastFailure com a data
(at), o status HTTP (statusCode, null quando não houve resposta, como em
timeout) e a categoria do erro (errorType) da última tentativa que falhou.
Nunca traz o corpo da resposta do seu servidor. Serve para corrigir o endereço
antes de a desativação automática acontecer.

Reativar: PATCH com isActive: true (exige API no plano). A reativação
zera a contagem e limpa disabledAt e disabledReason. Eventos disparados
enquanto o webhook esteve desativado não são enviados depois; reenvie as
entregas FAILED que precisar.

Liberação gradual: com o recurso desligado no ambiente nada é desativado nem
avisado.

Ver e reenviar entregas

Toda tentativa de disparo (entregue, falhada ou ignorada) fica registrada como
uma entrega, por endpoint.

Listar as entregas de um webhook, com filtro opcional por status
(PENDING, DELIVERED, FAILED, SKIPPED) e por event:

Ver o detalhe de uma entrega - inclui o corpo exato enviado (payload) e cada
tentativa, com o código HTTP e um recorte da resposta do seu endpoint
(responseSnippet):

Reenviar uma entrega FAILED ou SKIPPED (as únicas reenviáveis, exceto as de WEBHOOK_TEST, que se repetem chamando o teste de novo -
reenviar uma entrega já DELIVERED arriscaria seu sistema processar o mesmo
evento de novo, e uma entrega PENDING já está em curso):

O reenvio cria uma nova entrega, com o mesmo payload (mesmo id de
evento, para você deduplicar). Ele responde:

201 com a entrega nova - ou com uma entrega já em andamento
(PENDING) para o mesmo endpoint e evento, se você reenviar duas vezes
seguidas antes da primeira resolver;

409 se a entrega não estiver FAILED/SKIPPED, ou se o endpoint do
webhook tiver sido excluído ou desativado desde então;

404 se o webhookId ou o deliveryId não existirem, ou não
pertencerem à sua conta, ou a entrega pertencer a outro webhook.

Não há um teto próprio para reenvio manual: valem os limites gerais da conta
(requisições por minuto).

Resposta e retentativas#

Tabela de tentativas#

Status de uma entrega#

Idempotência e ordem#