Segurança de Webhooks

Protegendo o seu endpoint

Para a Clicksign se comunicar com a sua aplicação, você precisará de uma URL pública acessível. Sugerimos que a URL seja protegida para que requisições maliciosas não possam manipular seus dados.

Requisições HTTPS
Para garantir que os dados sejam criptografados, sugerimos fortemente a utilização de HTTPS na URL do seu webhook.

Autenticação básica HTTP
Servidores web podem ser configurados para utilizarem autenticação básica HTTP requerendo usuário e senha para acessar uma URL. Você pode configurar a URL do seu webhook passando usuário e senha através da URL. Exemplo: https://username:[email protected]/webhook.

Restrição de IPs via firewall
Se você estiver utilizando firewall, poderá configurá-lo para aceitar apenas requisições dos IPs dos webhooks da Clicksign:

HMAC

Introdução ao HMAC

HMAC é uma forma de verificar a integridade das informações transmitidas em um meio não confiável, i.e. a Internet, através de uma chave secreta compartilhada entre as partes para validar as informações transmitidas.

Quando um novo webhook é cadastrado, automaticamente é gerado um código HMAC SHA256 Secret. O objetivo dele é permitir que se tenha certeza de que o webhook foi enviado pela Clicksign e que os dados não foram comprometidos.

A cada disparado de webhook, a Clicksign calcula o Hash SHA256 da soma do Body da requisição com o Secret e adiciona essa informação ao cabeçalho. Exemplo: Content-Hmac: sha256=20dbdb06a522fb5046722c671bcf31f12be45485c425b6652c940546c397ea53.

O servidor que receber a requisição deve fazer o mesmo cálculo de Hash para verificar se a requisição de fato veio da Clicksign e de que os dados não foram comprometidos. Para isso, basta calcular o Hash SHA256 da soma do Body da requisição recebida com o Secret já conhecido. O valor deve ser igual ao enviado no cabeçalho da requisição.

Validador online de HMAC

https://www.freeformatter.com/hmac-generator.html
Utilize esta ferramenta informando o Body da requisição e o Secret. O resultado deverá ser o valor recebido no cabeçalho da requisição. Atenção: não formate o JSON antes do cálculo.

Exemplos de códigos

• PHP
• C#
• Node.js
• Ruby
• Java

Mais informações sobre HMAC

• RFC 2104 - IETF
• Wikipédia
• Stack Overflow