Webhooks: Visão Geral

Os Webhooks são a base de uma integração eficiente e escalável com a Clicksign. Eles permitem que sua aplicação reaja automaticamente às mudanças de estado dos documentos, sem a necessidade de solicitar informações repetidamente.
Em termos de arquitetura, os Webhooks transformam sua integração de um modelo passivo para um modelo reativo.

O que são?

Imagine que você está esperando uma encomenda.

Sem Webhook (Polling): Você liga para os correios a cada 10 minutos perguntando: "Já chegou?". Na maioria das vezes, a resposta é "Não". Isso gasta seu tempo e ocupa a linha telefônica deles.
Com Webhook: Você fornece seu número de telefone aos correios e diz: "Me ligue assim que o pacote chegar". Você fica livre para fazer outras tarefas e recebe a informação no instante exato em que o evento ocorre.

Tecnicamente, um Webhook é uma requisição HTTP POST que a Clicksign envia para uma URL configurada por você (endpoint), contendo um payload JSON com os detalhes do evento (ex: documento assinado, finalizado ou cancelado).

Por que usar Webhooks (vs. Polling)?

Uma prática comum, porém ineficiente, é o Polling — configurar um script (cron job) que consulta nossa API (GET /documents/:key) em intervalos fixos para verificar se o status mudou.

Abaixo, detalhamos por que você deve migrar de Polling para Webhooks:

Aspecto	Webhooks (Recomendado)	Polling (Desaconselhado)
Latência	Tempo Real: A notificação é enviada milissegundos após o evento.	Alta: O atraso depende do intervalo do seu script (ex: se o script roda a cada 10 min, seu atraso pode ser de até 9m59s).
Uso de Recursos	Eficiente: Processamento ocorre apenas quando há novidades.	Desperdício: 99% das chamadas são desnecessárias (recebem o mesmo status anterior).
Limites da API	Sem Impacto: Webhooks não consomem sua cota de requisições (Rate Limit).	Alto Risco: Polling agressivo pode estourar seu limite de requisições (Rate Limit), bloqueando operações legítimas.
Escalabilidade	Automática: Se o volume de assinaturas triplicar, você apenas recebe mais eventos.	Manual: Você precisaria reescrever sua lógica de loop para lidar com filas crescentes de documentos.

Nota de Arquitetura: O uso de Webhooks é considerado uma melhor prática para sistemas assíncronos. Evite construir rotinas de verificação de status (pooling), a menos que seja estritamente necessário por limitações de firewall, por exemplo.

Pollings e webhooks tem o mesmo objetivo, porém eles são muito mais eficientes, pois só transferem dados quando há uma atualização no recurso esperado. Segundo o Zapier, mais de 98,5% das requisições que realizam pollings são desperdiçadas. Isso significa que pollings geram, em média, 66x mais requisições do que webhooks.

Fonte: https://docs.cloud-elements.com. — fonte: https://docs.cloud-elements.com.

🚧
Limite de requisições
A Clicksign controla o limite de requisições realizadas. Não é permitido realizar polling em documentos. Se for necessário realizar essa prática por qualquer motivo, entre em contato com [email protected] solicitando permissão prévia.

Pronto para os próximos passos?

Agora que você entende o valor estratégico do gerenciamento automatizado de webhooks, direcione seu time técnico para as referências de implementação:

Referência Técnica (Endpoints)
Segurança de Webhooks – Para garantir a integridade da integração.
Melhores práticas - Aplique boas práticas à sua integração.
Eventos do Documento – Para escolher quais notificações fazem sentido para o seu produto.
Eventos do Aceite via Whatsapp – Para escolher quais notificações fazem sentido para o seu produto.

❓Precisa de ajuda? [email protected]

💰Dúvida sobre planos e preços? Veja o comparativo

🔍Não sabe qual versão está usando? Descubra a sua versão

📚Respostas rápidas? Visite nosso FAQ