Introdução
Webhooks são a espinha dorsal das integrações automatizadas entre o Affilentra, provedores de pagamento, ferramentas de contabilidade e sistemas de parceiros. Sem assinaturas seguras e proteção contra replay, essas conexões tornam‑se uma superfície de ataque: eventos manipulados, pagamentos duplicados ou faturas falsificadas podem surgir. Este artigo mostra de forma prática como comerciantes e operadores de rede na plataforma Affilentra self‑hosted assinam webhooks de entrada e saída, previnem ataques de replay e verificam integrações de forma robusta.
Princípios básicos da segurança de Webhooks
A proteção de webhooks baseia‑se em poucos, mas essenciais componentes:
- Segredos confidenciais (Shared Secrets) por integração
- Verificação da integridade da payload via assinatura (ex.: HMAC)
- Proteção contra replay mediante carimbo de tempo e nonces
- HTTPS/TLS para encriptação do transporte
- Registo, monitorização e rotação de chaves
O Affilentra suporta esses mecanismos por funções: os operadores de software gerem System‑Keys, os comerciantes definem os Secrets de integração e os parceiros recebem links de tracking e registos de pagamento auditáveis.
Webhooks de entrada: passos de validação para comerciantes
Quando terceiros (por exemplo, provedores de pagamento) enviam eventos à sua instância Affilentra, deve executar as seguintes verificações antes de acionar qualquer ação:
1) Verificação do transporte
- Aceitar apenas HTTPS. Redirecione pedidos HTTP para HTTPS ou rejeite‑os.
2) Validação da assinatura
Exija uma assinatura HMAC, gerada sobre o corpo bruto do pedido (raw request body) e um Secret partilhado. Nome de header recomendado: X‑Affilentra‑Signature. Procedimento:
- Calcule HMAC‑SHA256(raw_body, secret) → hex/base64
- Compare com o valor do header usando uma função de comparação de tempo constante
Importante: assine o texto bruto recebido exatamente (não o JSON parseado), para evitar problemas de canonicalization.
3) Timestamp e proteção contra replay
Solicite adicionalmente um carimbo de tempo no header (ex.: X‑Affilentra‑Timestamp) e verifique:
- O carimbo de tempo está dentro de uma janela curta (ex.: ±300 segundos) em relação à hora do sistema.
- Opcional: verifique um X‑Affilentra‑Nonce adicional e armazene nonces usados durante a duração da janela de tempo. Cada nonce só pode ser aceite uma vez.
Com Timestamp + Nonce evita‑se que um pedido interceptado seja reproduzido mais tarde.
4) Event‑ID e idempotência
Exija na payload um ID de evento exclusivo (p. ex. event_id). Defina que cada ID de evento seja processado uma vez; em entregas repetidas o processamento deve ser idempotente e deve devolver um estado 2xx com a indicação correspondente.
Outgoing Webhooks: Assinar Eventos do Affilentra
Quando a sua instalação Affilentra envia eventos para provedores de pagamento, sistemas de contabilidade ou parceiros, aplique: assine consistentemente as requests de saída e documente o formato para parceiros de integração.
Cabeçalho de Assinatura
- Incluir: X‑Affilentra‑Timestamp, X‑Affilentra‑Signature, opcional X‑Affilentra‑Nonce
- Signing‑String: concatenação de timestamp + '.' + raw_body
Exemplo de fluxo: timestamp = segundos UNIX atuais; signature = HMAC‑SHA256(timestamp + '.' + raw_body, provider_secret)
Entrega e Confirmação
- Espere do destinatário uma resposta 2xx. Em caso de 5xx ou falhas de rede: retries com backoff exponencial.
- Em 4xx: sem retries automáticos sem verificação manual (p. ex. 401 = assinatura/secret incorreto).
- Registe o Request, o código de resposta, a duração e o resultado da verificação da assinatura para auditorias.
Prevenir Ataques de Replay: Conceitos Práticos
A proteção contra replay combina mecanismos simples que, em conjunto, são eficazes:
- Janela de tempo curta para timestamps válidos (p. ex. 2–5 minutos).
- Armazenamento persistente de nonces/IDs de evento usados durante a duração da janela de tempo.
- Processamento idempotente através de verificações de ID de evento.
- Deteção de entregas múltiplas: classes de logging diferenciadas (aviso vs. erro).
Num ambiente self‑hosted como o Affilentra pode armazenar caches de nonce no Redis ou na base de dados com TTL; é importante que o armazenamento seja rápido o suficiente para verificar pedidos paralelos de forma consistente.
Verificação e Tratamento de Erros
Os casos de erro devem ser transparentes e tratáveis:
- Em erros de assinatura: 401 Unauthorized + logging com Request‑ID, mas sem conteúdo da payload nos logs, quando estiverem envolvidas dados sensíveis.
- Em erros de Timestamp/Nonce: 400 Bad Request com descrição clara do erro no corpo.
- Em entregas repetidas: 200 OK, se o evento já tiver sido processado, e fornecer um indicador, p. ex. {"status":"duplicate","event_id":...}.
- Alerta: em caso de taxa incomumente alta de erros de assinatura ou timestamp: alertas automáticos para operadores e comerciantes.
Recomendações Operacionais & Gestão de Secrets
A gestão baseada em funções é central no Affilentra: operadores de software administram a plataforma, comerciantes configuram os secrets de integração, parceiros usam chaves dedicadas. Medidas recomendadas:
- Um Secret separado por integração; não reutilize.
- Armazene Secrets em variáveis de ambiente ou em repositórios de segredos (por exemplo, HashiCorp Vault); nunca no código ou em repositórios públicos.
- Rotação regular de chaves (por exemplo, a cada 90 dias) com uma fase de transição em que as chaves antigas e novas são aceitas.
- Registos de auditoria para uso e rotação de chaves.
- Restringir acessos por IP aos endpoints de Webhook, quando possível (lista branca) — como medida complementar, não substituta das assinaturas.
Exemplo prático: Fluxo HMAC‑SHA256 (conceitual)
Assim pode ser um fluxo mínimo de assinatura na Affilentra:
- Remetente: gera timestamp, raw_body e nonce; signature = HMAC‑SHA256(timestamp + '.' + raw_body, shared_secret).
- Remetente: envia um POST ao destinatário com os cabeçalhos X‑Affilentra‑Timestamp, X‑Affilentra‑Nonce, X‑Affilentra‑Signature e raw_body.
- Destinatário (Affilentra): verifica TLS, lê raw_body, valida o timestamp em relação à hora do sistema, verifica o cache de Nonce, calcula o HMAC e compara assinaturas em tempo constante, valida event_id e processa de forma idempotente.
Estes passos são propositadamente simples; na implementação deve assegurar comparações em tempo constante, nonces aleatórios seguros e registos de erro robustos.
Notas orientadas por funções para utilizadores da Affilentra
- Comerciantes: Crie Secrets separados por Payout‑Provider e ferramenta de contabilidade. Utilize as configurações da Affilentra para tornar os requisitos de assinatura obrigatórios.
- Operadores de rede: Providencie um monitoramento central e exija cabeçalhos de verificação de integridade junto dos parceiros. Utilize as edições PRO & NETWORK para atribuição granular de permissões.
- Parceiros/Publishers: Verifiquem os Webhooks da Affilentra recebidos localmente antes de processar e documentem os cabeçalhos esperados e Event‑IDs.
Conclusão e próximo passo
Operar Webhooks de forma segura requer a aplicação consistente de assinaturas, proteção contra replay e controlos operacionais. Na plataforma Affilentra self‑hosted pode configurar estes mecanismos com base em funções e assim proteger de forma fiável integrações com Payout‑Providers, ferramentas de contabilidade e sistemas de parceiros. Se procura uma solução segura, auto‑hospedada, com licença permanente e sem partilha de receitas, considere as edições PRO & NETWORK.
Aja agora: Escolha o seu ponto de entrada e descubra como a Affilentra protege robustamente as suas integrações de Webhook: https://affilentra.de
Próximo passo
Experimentar a Affilentra
Plataforma unificada que reúne de forma transparente fornecimento de produtos, rastreamento, validação de conversões, cálculo de comissões e pagamentos ao longo de funções claramente separadas; opção de instalação auto‑hospedada com licença perpétua sem participação nas receitas; comerciantes mantêm controle sobre produtos, condições e materiais promocionais; parceiros recebem links de rastreamento pessoais e um histórico de pagamentos rastreável.