Webhooks

Eventos

O tipo do evento vem no header X-Sign-Event e espelha o ciclo do envelope e dos signatários. Exemplos frequentes:

• envelope.created — envelope persistido
• envelope.sent — convites disparados
• signer.signed — signatário concluiu
• envelope.completed — fluxo finalizado
• envelope.canceled — cancelamento

Headers e corpo

• Content-Type: application/json
• X-Sign-Event — tipo do evento
• X-Sign-Timestamp — milissegundos (string); use na verificação HMAC e para janela anti-replay
• X-Sign-Signature — formato sha256=<hex>

Assinatura HMAC

Calcule HMAC-SHA256 com o secret do webhook sobre a string timestamp + "." + rawBody (body bruto, bytes UTF-8). Compare com o header após o prefixo sha256=. Não parseie o JSON antes de validar — frameworks costumam consumir o stream; guarde o raw body.

const raw = req.body.toString('utf8') // ou buffer → string
const ts = String(req.headers['x-sign-timestamp'] ?? '')
const sig = String(req.headers['x-sign-signature'] ?? '')
const expected = 'sha256=' + hmacHex(secret, ts + '.' + raw)
// comparar em tempo constante com sig

Timestamp e replay

O timestamp faz parte da string assinada. Em produção, rejeite entregas fora de uma janela razoável (ex.: minutos) para limitar replay, além de validar o HMAC.

Retry e fila

As entregas são enfileiradas e reexecutadas com backoff até um limite de tentativas. O mesmo evento pode ser reentregue após falha na sua URL — o desenho idempotente do seu handler (por id de envelope ou id de entrega) evita efeitos colaterais duplicados.

No portal, quando disponível para o tenant, é possível inspecionar entregas e usar ações de retry/replay alinhadas à operação documentada.

Troubleshooting rápido

• 401/403 no seu endpoint — confirme rota pública, método POST e corpo legível.
• Assinatura inválida — confira secret atual (após rotação use o novo valor), raw body exato e ordem timestamp + "." + body.
• Timeouts — responda 2xx o mais rápido possível e processe em fila interna; o provedor pode marcar falha e retentar.