Introdução
As integrações de webhook são a espinha dorsal dos pagamentos automáticos e do processamento de conversões em redes de parceiros. Retries incorretos, falta de idempotência ou estratégias de backoff agressivas podem causar pagamentos duplicados, perdas de conversões ou incoerências temporais. Para operadores da Affilentra e parceiros de integração, é essencial implementar regras claras e testadas na prática. Este guia mostra, em passos concretos, como conceber retries de webhook, backoff e idempotência para que notificações de payout e eventos de conversão sejam processados de forma consistente, rastreável e segura.
Responsabilidades: Remetente vs. Receptor
Funções claras para a Affilentra fazem parte do conceito: a plataforma atua como remetente de eventos (conversões, notificações de payout), enquanto os sistemas do comerciante e os endpoints dos parceiros são os receptores. Defina obrigatoriamente:
- Remetente (Affilentra): Fornece metadados de evento exclusivos (event_id, tipo, timestamp, payload_hash, assinatura) e implementa um mecanismo de retry consistente com backoff.
- Receptor (Comerciante/Parceiro): Verifica a assinatura, usa o event_id para verificação de idempotência e toma precauções contra processamento concorrente.
Componentes-chave de uma estratégia robusta
Os seguintes blocos são indispensáveis para um processamento fiável:
- Unique Event‑ID: Cada mensagem de webhook contém um ID imutável e globalmente único.
- Idempotency‑Key: Definido pelo remetente ou o receptor utiliza o event_id como Idempotency‑Key.
- Assinatura/Autenticação: HMAC ou equivalente para proteção e deteção de replay.
- Retry‑Policy com Backoff: Backoff exponencial, jitter, número máximo de retries e tratamento de dead‑letter.
- Protocolo de processamento: Armazenamento persistente, incluindo estado (received, processing, succeeded, failed, dead_letter).
Passos práticos de implementação para operadores da Affilentra (Remetente)
1. Estrutura de evento padronizada
Cada mensagem deve conter pelo menos os seguintes campos: event_id, event_type, created_at, payload, payload_hash, signature. Garanta que o event_id permaneça globalmente único (UUID v4 ou equivalente).
2. Mecanismo de Retry com Backoff e Jitter
Recomendação: Backoff exponencial com jitter aleatório reduz o efeito de "thundering herd". Fluxo de exemplo (como orientação): tentativa imediata inicial, seguido de intervalos que crescem de forma exponencial até um máximo; um número total limitado de tentativas. Adicione um mecanismo de dead‑letter quando o receptor estiver permanentemente inacessível — a gestão operacional deve receber notificações para tratamento manual posterior.
3. Interpretação de códigos de resposta
Interprete claramente códigos HTTP: 2xx é considerado sucesso (sem novos retries), 4xx como erro permanente (sem retries, mas com relatório de erro), 5xx e timeouts como erro temporário (retry após backoff). Registe respostas incluindo headers e corpo para depuração.
4. Enviar metadados de idempotência
Forneça além do evento uma recomendação de header de idempotência: por exemplo X-Affilentra-EventID: {event_id} e X-Affilentra-Signature. Assim os destinatários recebem todas as informações necessárias para identificação segura.
Passos práticos de implementação para destinatários (Merchants / Partners)
1. Verificação de assinatura e proteção contra replay
Verifique a assinatura imediatamente. Se a assinatura for inválida, responda com 401 e registe o incidente. Defina uma janela temporal aceitável para replay: eventos fora dessa janela devem ser verificados separadamente.
2. Verificação de idempotência: armazenamento persistente do estado do evento
Use event_id como chave primária ou como coluna de índice único numa tabela dedicada. Antes de processar, execute uma operação atômica: INSERT IF NOT EXISTS com estado 'processing' e atualize para 'succeeded' após processamento bem‑sucedido. Se o INSERT falhar (já existente), leia o estado e decida: já bem‑sucedido → nenhuma ação; em processamento → opcionalmente aguarde bloqueio ou recuse com 409.
3. Operações de negócio atômicas
Evite efeitos colaterais antes de concluir a verificação de idempotência. Em Payouts: verifique se a liquidação para event_id já foi executada (p.ex. entrada de payout referenciando event_id). Use transações de base de dados ou constraints únicas para evitar pagamentos duplicados.
4. Política de resposta segura
Ao aceitar com sucesso, retorne 200/202. Em erros temporários 5xx ou timeout — permita que o remetente reenvie. Em conflitos (duplicado/estado inconsistente) retorne 409 e inclua um texto de erro explicativo.
Patterns de idempotência e detalhes técnicos
Os seguintes padrões comprovados:
- Tabela de Idempotência: Tabela com colunas: event_id, request_body_hash, status, result_payload, last_update. Armazenar o resultado permite responder imediatamente sem reprocessamento.
- Pattern de Unique‑Constraint: Aplique um constraint único em event_id na tabela de negócio (p.ex. payouts). Tentativas de gravar o mesmo pagamento repetidas vezes falham — assim evita‑se duplicação.
- Optimistic Locking / Compare‑And‑Set: Útil para processos concorrentes quando múltiplos workers processam eventos em paralelo.
- Locks de curta duração: Implemente locks com expiração (p.ex. Redis‑Lock com TTL) para evitar deadlocks.
Monitorização, Observability e tratamento de erros
Instrumente endpoints e remetentes: métricas para eventos enviados, entregas bem‑sucedidas, retries e dead‑letters. Registe latências, taxas de erro e a distribuição dos intervalos de retry. Com base nestas métricas ajuste os parâmetros de backoff e o número máximo de tentativas.
Observações específicas para Payouts vs. Conversion‑Events
Os payouts são financeiramente mais sensíveis do que simples notificações de conversion. Portanto aplica‑se:
- Payouts: Idempotência rigorosa: registos de pagamento devem ter uma referência única event_id e um estado verificado. Antes de transferências externas, verifique referências duplicadas. Em caso de dúvidas: ciclo de liberação manual em vez de uma cascata automática de retries.
- Conversions: Aqui costuma ser suficiente um processamento agregado, contudo as conversions têm de ser atribuídas de forma inequívoca e desduplicadas em caso de entregas múltiplas (verifique event_id ou o Payload‑Hash).
Casos de erro e recuperação
Defina processos para estes cenários:
- Evento foi recebido, mas o processamento falha — defina o estado como 'falhado' com detalhe do erro; permita re‑enfileiramento controlado ou revisão manual.
- Receptor permanentemente inacessível — o remetente coloca o evento na dead‑letter e informa os operadores; o operador decide sobre retries, repetição manual ou cancelamento.
- Processamento parcial (ex.: base de dados em estado inconsistente) — ofereça endpoints de reparação ou ferramentas de administração que mostrem o histórico de eventos e permitam reconciliação.
Integração no modelo operacional da Affilentra
Affilentra fornece uma arquitetura self‑hosted e papéis separados para operadores de software, comerciantes e parceiros. Isso permite aos operadores configurar e oferecer centralmente os mecanismos aqui descritos: gerir chaves de assinatura, definir políticas de retry, estabelecer fluxos de trabalho de dead‑letter e disponibilizar protocolos de webhook. Os comerciantes mantêm o controlo sobre regras de payout; os parceiros veem mensagens de estado transparentes e podem confiar em respostas de evento idempotentes.
Resumo e recomendações de implementação
Implemente a estratégia de forma gradual: 1) introduza formatos de evento e assinaturas padronizadas; 2) implemente um Idempotency‑Storage e constraints únicos; 3) configure backoff exponencial com jitter e tratamento de dead‑letters; 4) estabeleça monitorização e processos de recuperação. Documente claramente o comportamento para os parceiros de integração e forneça exemplos de headers e códigos de resposta.
Affilentra apoia‑lo nisso como plataforma self‑hosted com papéis claramente separados, metadados de evento auditáveis e opções de configuração para retries e dead‑letters. Para operadores e parceiros de integração isto significa: controlo, rastreabilidade e menor risco de eventos duplicados ou perdidos.
Agir agora: Para implementar com segurança a sua estratégia de webhook, escolha o seu ponto de entrada na Affilentra: Escolher entrada
Próximo passo
Experimentar a Affilentra
Plataforma unificada que integra de forma transparente a disponibilização de produtos, tracking, validação de conversões, cálculo de comissões e pagamento ao longo de papéis claramente separados; opção de instalação self-hosted com licença perpétua sem participação nos rendimentos; comerciantes mantêm o controlo sobre produtos, condições e materiais promocionais; parceiros recebem links de tracking pessoais e um histórico de pagamentos rastreável.