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 nosso Time de Suporte, 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? Entre em contato com o Suporte

💰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