Webhooks: como funciona

Webhooks são notificações que o TapSign envia para a sua aplicação quando algo acontece em um documento. Em vez de consultar a API repetidamente (polling), você recebe um POST na sua URL no momento do evento.

Como funciona na prática

1. Você registra uma URL HTTPS pública, um segredo e a lista de eventos, pelo painel do TapSign em Integrações > Webhooks ou pela API (Criar Webhook).
2. Quando um evento acontece em um envelope do qual você é o dono, o TapSign monta o payload em JSON e faz um POST para cada webhook ativo que escuta aquele evento.
3. Cada entrega leva o header X-Webhook-Signature com o HMAC-SHA256 do corpo, calculado com o seu segredo (Verificação de Assinatura).
4. Sua aplicação responde com qualquer status 2xx. Outra resposta, erro de conexão ou timeout conta como falha e a entrega é retentada.

┌─────────┐   evento   ┌──────────────┐   POST + X-Webhook-Signature   ┌────────────────┐
│ TapSign │ ─────────► │ Envio do     │ ─────────────────────────────► │ Sua aplicação  │
└─────────┘            │ webhook      │                                └────────────────┘
                       └──────────────┘ ◄───────────── HTTP 2xx ──────────────────┘

Polling ou webhooks

Abordagem	Polling	Webhooks
Tempo real	Não (depende do intervalo)	Sim
Consumo do rate limit	Alto (muitas requisições)	Nenhum (o TapSign chama você)
Complexidade	Precisa manter um loop de consulta	Recebe automaticamente

Eventos disponíveis

Evento	Quando dispara
doc_viewed	Um signatário abriu o link de assinatura do documento.
doc_signed	Todos os signatários assinaram e o PDF assinado ficou pronto. Sai junto com doc_completed.
doc_refused	Um signatário recusou assinar (vem com rejected_reason).
doc_completed	Todos os signatários assinaram e o PDF assinado ficou pronto (vem com signed_file).
doc_canceled	O envelope foi cancelado.
doc_expired	O prazo do envelope venceu sem que ele fosse concluído.
*	Assina todos os eventos acima.

doc_signed não avisa cada assinatura

Apesar do nome, hoje o doc_signed só é enviado quando o envelope inteiro foi assinado, junto com o doc_completed. Não existe evento por assinatura individual. Para acompanhar quem já assinou, consulte Detalhar Documento.

O conteúdo de cada evento está em Eventos.

Regras de entrega

• Dono do envelope: os eventos vão para os webhooks ativos do usuário dono do envelope. Webhooks de outros usuários não recebem eventos desse envelope.
• HTTPS público: a URL precisa usar HTTPS e não pode apontar para endereço privado, loopback ou link-local. Ela é validada no cadastro, na atualização e de novo a cada envio.
• Timeout: 5 segundos para conectar e 15 segundos para ler a resposta.
• Só 2xx é sucesso: redirecionamentos (3xx) não são seguidos e contam como falha.
• Retentativas: até 5 tentativas no total, com intervalo crescente. Veja a política de retentativas.
• Ordem não garantida: os envios são assíncronos. Trate cada evento de forma independente, inclusive doc_signed e doc_completed.

Guia no Central de Ajuda

Para uma visão sem código de como configurar chaves de API e webhooks no painel, veja API e webhooks no Central de Ajuda do TapSign.

Próximos passos

• Criar Webhook: registre sua primeira URL
• Eventos: payload completo de cada evento
• Logs de Entrega: monitore e reenvie entregas
• Verificação de Assinatura: valide a autenticidade dos webhooks
• Excluir Webhook: remova webhooks que não usa mais