Webhooks: como receber e conferir o aviso de documento assinado

Esta página faz parte de Integrações: conectar seu sistema ao Sonarview Sign (API). Comece por lá se ainda não criou a sua chave.

Segredo do webhook

Se o seu sistema quiser ser avisado automaticamente quando um documento é assinado, ele recebe um aviso (webhook). O Segredo do webhook serve para o seu sistema confirmar que o aviso veio mesmo do Sonarview Sign.

Como conferir a assinatura do aviso

Cada aviso chega com um cabeçalho:

X-Sonar-Signature: keyId=<identificador da chave>,sha256=<HMAC do corpo>

A conferência tem três passos, e a ordem importa:

1. Leia o keyId do cabeçalho.
2. Procure esse keyId na lista que a API devolve (veja abaixo) e pegue o segredo correspondente.
3. Recalcule o HMAC-SHA256 do corpo cru (os bytes exatamente como chegaram, antes de qualquer leitura como JSON) e compare com o sha256 do cabeçalho.

Sobre o corpo cru: se o seu código transformar o corpo em objeto e depois voltar a texto, a assinatura não vai fechar. A ordem dos campos e os espaços podem mudar nessa ida e volta, e o HMAC cobre os bytes originais.

Existe mais de um segredo válido ao mesmo tempo, e o seu sistema precisa aceitar todos

Quando o seu sistema busca o segredo pela API, a resposta não traz um segredo: traz uma lista, no campo secrets. Cada item tem o seu keyId e o seu alcance:

A regra, e ela evita a única falha grave desta integração: aceite qualquer keyId que esteja na lista secrets, não apenas o primeiro. Um sistema que guarde um único segredo e recuse os outros funciona hoje e para de funcionar sem aviso no dia em que a assinatura passar a usar o segredo da organização.

Se chegar um keyId que você não conhece: busque a lista de novo na API antes de recusar o aviso. Um keyId desconhecido quase sempre quer dizer que há um segredo novo, não que alguém está falsificando. Recusar de imediato faz perder avisos legítimos.

O que o aviso afirma sobre a origem, e até onde essa afirmação vale

O corpo do aviso identifica de quem é o documento e traz um campo chamado signed_scope. Ele diz o que a chave que assinou consegue provar, e não é detalhe:

Por que dizemos isto em vez de calar: uma afirmação assinada convida quem recebe a parar de conferir. Se entregássemos o identificador da organização sem dizer o alcance da chave, uma organização poderia escrever o identificador de outra da mesma conta e a conferência fecharia: assinada, conferida e errada. O signed_scope existe para que a sua conferência saiba quando pode confiar e quando tem de conferir por fora.

Uma nota sobre o que muda com o tempo: o alcance da assinatura depende da configuração da conta e pode mudar sem aviso prévio para o seu sistema. É por isso que ele se lê do campo, nunca se presume. Nada disso quebra o seu sistema se ele seguir as duas regras acima: aceitar qualquer keyId da lista e ler o signed_scope em vez de presumi-lo.

Se o aviso não chegar: quantas vezes tentamos, e até quando

O aviso pode falhar por um motivo simples: o sistema da sua empresa estava fora do ar no momento em que o documento foi assinado. Quando isso acontece, nós tentamos de novo sozinhos, mas não para sempre, e essa última parte é a que precisa ficar clara.

Insistimos por cerca de 7 dias.

E os 7 dias não são palpite: são resposta a uma medição. Perguntamos a um dos sistemas que nos recebe por quanto tempo, no pior caso, ele responde 503. A resposta foi que não há limite: o 503 dele aparece quando ele não consegue ler um dado que vem de nós, ou seja, dura o que durar uma falha do nosso lado. Nenhum número finito cobre isso. Os 7 dias cobrem uma parada longa; o que passar disso fica com o pedido de reenvio.

O que decide agora não é a contagem: é o motivo da falha

A única coisa desta página que você pode acionar sem saber: o 410. Para nós, 410 Gone quer dizer, por contrato, “este endereço não existe mais, não volte”. É o único código que nos faz desistir na hora.

Se o seu sistema devolve 410 em um endereço que ainda usa (alguns servidores fazem isso para caminhos aposentados, ou por configuração de um proxy), ele está desligando o próprio aviso, e nós obedecemos. Nesse caso, devolva 503 ou 404.

Quanto tempo entre uma tentativa e a seguinte

Passados os ~7 dias, o aviso daquele documento não volta sozinho, nem quando o seu sistema voltar. Não há alarme do seu lado e não há e-mail para você: simplesmente não chega nada, e parece que ninguém assinou.

O que fazer nesse caso, e é simples: quem integra pede o reenvio pela API (POST /v1/webhook/resend, com o número da solicitação). Funciona mesmo depois de termos parado de tentar, e pode ser pedido a qualquer momento. O que ele não corrige é um endereço recusado nem um 410: nesses dois casos, corrija o endereço primeiro.

E a regra que evita o problema todo: o aviso é uma comodidade, não é a fonte da verdade. Quem precisa de certeza consulta o estado da solicitação pela API. Conferir o estado uma vez por dia recupera os documentos cujo aviso não chegou: a consulta devolve o estado atual, independentemente do que aconteceu com o aviso.

Falta o aviso de um documento que você sabe que foi assinado? Peça o reenvio (abaixo): ele recupera o aviso a qualquer momento, independentemente de há quanto tempo o documento foi assinado.