Sobre o webhook

Webhooks são notificações em tempo real enviadas via HTTP POST para um endpoint configurado pelo parceiro, sempre que um evento específico ocorrer no sistema.

✅ Guia de Validação de Assinatura Digital

Visão Geral

Este guia descreve o processo de validação de assinaturas digitais usando o algoritmo ECDSA (Elliptic Curve Digital Signature Algorithm) em conjunto com o hash SHA3-256. Este processo garante a autenticidade e integridade dos dados recebidos.

Requisitos Técnicos

• Chave pública do emissor (formato PEM)
• Payload (dados) a ser verificado
• Assinatura digital em formato base64

Processo de Validação

1. Preparação dos Dados
   O payload deve estar em formato de bytes (UTF-8)
   A assinatura deve estar em formato base64
   Certifique-se que tanto o payload quanto a assinatura não estejam vazios
2. Validação da Assinatura
   Para validar a assinatura, você precisará:
   1. Decodificar a assinatura do formato base64
   2. Utilizar a chave pública para verificar se a assinatura corresponde ao payload
   3. Utilizar o algoritmo ECDSA com SHA3-256 para a verificação
3. Interpretação dos Resultados
   • Se a validação for bem-sucedida, significa que:
     • O payload não foi alterado desde sua assinatura
     • A assinatura foi realmente gerada pelo detentor da chave privada correspondente
   • Se a validação falhar, isso pode indicar:
     • Alteração no payload original
     • Assinatura inválida ou corrompida
     • Uso de uma chave pública incorreta

Observações Importantes

• Mantenha a chave pública em local seguro
• Certifique-se de usar a versão correta da chave pública do emissor
• Em caso de erros durante a validação, verifique se:
  • O formato do payload está correto
  • A assinatura está corretamente codificada em base64
  • A chave pública corresponde ao emissor esperado
    

Tratamento de Erros
Os seguintes erros podem ocorrer durante a validação:

• Payload ou assinatura vazios
• Erro no formato da assinatura base64
• Assinatura inválida para o payload fornecido

🚧

Observações

Em qualquer desses casos, o sistema retornará um erro apropriado indicando o problema específico encontrado.

Exemplo de Validação:

from base64 import b64decode
from cryptography.hazmat.primitives.asymmetric import ec
from cryptography.hazmat.primitives import serialization
from cryptography.hazmat.primitives.hashes import SHA3_256
from cryptography.exceptions import InvalidSignature
 
# 1. Carregar a chave pública
with open('chave_publica.pem', 'rb') as arquivo:
    chave_publica = serialization.load_pem_public_key(arquivo.read())
 
# 2. Preparar o payload para verificação
payload = {
    "id": "123",
    "valor": 100.00,
    "data": "2025-06-23"
}
# Converter o payload para bytes
payload_bytes = json.dumps(payload).encode('utf-8')
 
# 3. Exemplo de assinatura recebida (em base64)
assinatura_base64 = "SUhBUExBVEFGT1JNQStmc2RmZ..." # exemplo fictício
 
# 4. Verificar a assinatura
try:
    # Decodificar a assinatura de base64
    assinatura = b64decode(assinatura_base64)
    # Realizar a verificação
    chave_publica.verify(
        signature=assinatura,
        data=payload_bytes,
        signature_algorithm=ec.ECDSA(SHA3_256())
    )
    print("Assinatura válida!")
except InvalidSignature:
    print("Assinatura inválida!")
except ValueError as e:
    print(f"Erro na validação: {str(e)}")

⚙️ Mecanismo de Retentativa e Resiliência

🔄 Fila de Processamento Assíncrono
Notificações são enfileiradas em um sistema de mensageria para garantir entrega mesmo em falhas temporárias.

Mensagens permanecem na fila até:

Entrega bem-sucedida (HTTP 200), ou

Limite de retentativas esgotado (5 tentativas).

⏱️ Política de Reenvios
Backoff Exponencial: Intervalos crescentes entre tentativas:

1 minuto → 2 minutos → 4 minutos → 8 minutos → 16 minutos.

Timeout por Requisição: 15 segundos.

🔴 Circuit Breaker
Se um endpoint parceiro apresentar alta taxa de falhas (ex.: 5 erros consecutivos), as notificações para ele serão pausadas automaticamente por 1 hora.

📜 Exemplo de Fluxo de Erro
1ª tentativa: Falha (timeout).

2ª tentativa: Falha (HTTP 500).

3ª tentativa: Sucesso (HTTP 200).

✅ Notificação removida da fila.

Cenário de falha total: Após a 5ª tentativa sem sucesso, a notificação é arquivada para análise manual.

🚧

Observações

Não há ação necessária para notificações falhas (o sistema gerencia retentativas).