Webhooks — Entregas, retentativas e reenvio - SuperSign

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 o mais rápido possível.

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

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`.

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}.

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 —
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).

Webhooks — Entregas, retentativas e reenvio

Resposta e retentativas#

Tabela de tentativas#

Status de uma entrega#

Idempotência e ordem#

Ver e reenviar entregas#

Resposta e retentativas

Tabela de tentativas

Status de uma entrega

Idempotência e ordem

Ver e reenviar entregas