Validar assinatura da notificação

Visando garantir autenticidade e segurança, nossos webhooks possuem em todas as chamadas o parâmetro signature.

A assinatura de webhook é um elemento crucial para garantir a autenticidade e a integridade das notificações enviadas. Este parâmetro é uma assinatura digital que permite ao receptor da notificação verificar se a mensagem foi realmente enviada pelo nosso sistema e se não foi alterada durante o trânsito. A ausência de uma validação adequada pode expor sua aplicação a riscos de segurança, como ataques de replay e injeção de dados maliciosos.

Guia para validar a assinatura das notificações

• Obtenha a chave pública de sua conta: A chave pública de sua conta Grafeno pode ser obtida acessando: "Cobranças" >>> "Base de Cobranças" >>> "Ações" (em qualquer cobrança) >>> "Chave pública da API". A chave pública deve ser salva num arquivo com a extensão .pem.
• Obtenha a mensagem: Em todas as notificações, enviamos no header o dado x-unique-key, este dado se refere a mensagem que deve ser validada e ele é formado por um uuid V4 e o status da notificação, exemplo: 31216ba1-c507-688c-bea7-b7adf8cf2c1c-boleto-criado.
• Faça o decode do parâmetro "signature": O parâmetro signature está em Base64, para a validação deste parâmetro, é necessário fazer o decode.

Código exemplo para validar a assinatura

from cryptography.hazmat.primitives import hashes
from cryptography.hazmat.primitives.asymmetric import padding
from cryptography.hazmat.primitives.asymmetric import rsa
from cryptography.hazmat.primitives import serialization
from cryptography.exceptions import InvalidSignature
import base64

def load_public_key(pem_path):
    with open(pem_path, "rb") as key_file:
        public_key = serialization.load_pem_public_key(key_file.read())
    return public_key

def verify_signature(public_key, message, signature):
    try:
        public_key.verify(
            signature,
            message,
            padding.PKCS1v15(),
            hashes.SHA256()
        )
        return True
    except InvalidSignature:
        return False

public_key = load_public_key("Informe aqui o path até o arquivo .pem contendo a sua chave pública.")

message = b"Informe aqui o valor do header x-unique-key."  
signature_b64 = """Informe aqui o valor do parâmetro signature recebido no body do webhook.""" 

signature = base64.b64decode(signature_b64)

is_valid = verify_signature(public_key, message, signature)

if is_valid:
    print("Assinatura válida.")
else:
    print("Assinatura inválida.")

🚧

Segurança

A validação da assinatura dos webhooks é um passo essencial para manter a segurança e a integridade das notificações. Certifique-se de implementar este processo conforme descrito para proteger sua aplicação contra acessos não autorizados e garantir que apenas notificações legítimas sejam processadas.