Segurança

Verificação de assinatura (HMAC)

É possível habilitar durante a criação de novas assinaturas que os eventos sejam assinados (HMAC). Com esta verificação o cliente consegue garantir que o evento é de fato originado da 180 Seguros e não sofreu qualquer alteração. Além disso, um timestamp é incluído no payload assinado, o que permite ao cliente ignorar mensagens que venham a ser entregues muito após o envio (ataques de replay).

📘

A URL de destino para os eventos é validada no momento da criação da assinatura com a tentativa de entrega de um evento "ping" de forma síncrona. Se isso não for desejável, por exemplo se o endpoint exigir verificação HMAC desde o início, basta seguir os seguintes passos:

• Crie a assinatura no estado inativo (ativo: false)
• Configure a chave de assinatura HMAC obtida na resposta anterior na sua lógica de validação no endpoint
• Quando o endpoint já estiver apto a validar o header i80-signature conforme as instruções abaixo, atualize a assinatura para o estado ativo (ativo: true).

Para habilitar HMAC nos eventos basta enviar o campo "hmac-habilitado": true no request de criação da assinatura . Não é possível atualizar uma assinatura existente para habilitar HMAC ou desabilitar a feature após ativada.

A chave usada para verificação das assinaturas será retornada na resposta da chamada descrita acima no campo "chave-assinatura-hmac". Este é o único momento em que a chave será retornada. Caso a mesma seja perdida, será necessário remover a assinatura atual e criar uma nova.

Fluxo de verificação

Para assinaturas ativas com a feature de HMAC habilitada, as entregas dos eventos de webhook incluirão um header adicional i80-signature. O formato do valor do header é t={timestamp},{version}={signature}, com os components separados por vírgula, onde:

• timestamp: é o momento em que o evento foi enviado, em segundos. Este valor, exatamente como está presente no header, faz parte do payload assinado e pode ser usado pelo cliente para ignorar eventos recebidos muito após o envio. Exemplo de valor: 1760635045
• version e signature: são os pares que contêm as assinaturas de fato. No momento, version será sempre v1. signature é a string em hexadecimal que é a assinatura do payload e que será usada para verificação. Este par de valores pode aparecer mais de uma vez quando a chave está sendo rotacionada.

Exemplos de headers completos:

t=1760635045,v1=2856686d3bd02d578bec3447d2f14c86446601600fa6e9133dfb147721edcb45

t=1760635045,v1=2856686d3bd02d578bec3447d2f14c86446601600fa6e9133dfb147721edcb45,v1=dbffe192ea63eddd57ab9965a57b5d0bc6eaa9570f2ede6028c5ad1bbd038bcf

Para validar a assinatura:

• Construa o payload assinado concatenando o timestamp do header, um ponto final (.) e o conteúdo puro do evento recebido, sem qualquer alteração (timestamp + "." + corpo-do-evento). Exemplo: para um payload {"id":123} e o timestamp 1760635045, o payload a ser verificado é 1760635045.{"id":123}
• Calcule a função HMAC usando o algoritmo HMAC-SHA256 com a chave obtida na criação da assinatura e o payload acima. O resultado deve ser codificado em hexadecimal.
• Compare o resultado anterior com qualquer uma das assinaturas presentes no header i80-signature. Se houver um sucesso, a verificação passou e o evento é legítimo. Caso contrário, descarte o evento.
• Considere o timestamp e quanto tempo faz desde que o evento foi enviado e descarte-o se for muito antigo.

Rotacionar chaves

Utilize o endpoint Rotacionar chave HMAC para gerar uma nova chave, que inicialmente será uma chave adicional secundária. Os eventos entregues após a geração dessa nova chave já serão entregues com duas assinaturas no header i80-signature.

A chave secundária gerada se tornará a chave principal e única em 7 dias. Dentre deste período o cliente precisa atualizar o segredo em sua lógica de verificação para usar a nova chave.

Caso o endpoint Rotacionar chave HMAC seja chamado e já exista uma chave secundária, a mesma será sobrescrita por uma nova chave. O prazo de 7 dias para que esta se torne a chave principal é reiniciado. A chave sendo utilizada antes do início de uma rotação nunca é sobrescrita antes de se passarem os 7 dias coexistindo com uma chave secundária.

Segredo compartilhado

É possível configurar um segredo compartilhado durante a criação de assinaturas de webhooks com o campo segredo-compartilhado. Este mesmo segredo será apresentado durante a entrega de eventos da assinatura correspondente no header HTTP padrão Authorization: Bearer SEGREDO_COMPARTILHADO.

O segredo configurado nunca é exposto novamente pela API de gerenciamento. Caso necessário, basta atualizar a assinatura com um novo segredo.

Nas respostas da API o campo booleano envia-header-de-autorizacao indica se existe ou não um segredo cadastrado em cada assinatura.

📘

Validação do endpoint durante a criação

Note que o endpoint informado durante a criação de assinaturas de webhook é validado no momento de criação. A chamada inicial já vai conter o header com o segredo compartilhado (se informado) e o endpoint, se for protegido, já precisa aceitá-lo.