Como os Webhooks Impulsionam o Rastreamento de Afiliados
Os webhooks são a espinha dorsal do rastreamento moderno de afiliados em apps mobile. Eles conectam seu serviço de verificação de compras à sua plataforma de afiliados em tempo real, garantindo que cada compra qualificada seja atribuída ao parceiro afiliado correto sem intervenção manual.
Compreender os padrões comuns de integração de webhooks ajuda você a construir um pipeline de rastreamento de afiliados confiável e fácil de manter.
O Fluxo Básico de Webhook
O fluxo padrão para rastreamento de afiliados via webhooks segue esta sequência:
- Um usuário clica em um link de afiliado e é atribuído a um parceiro afiliado
- O usuário instala o app e eventualmente faz uma compra
- A loja de aplicativos processa o pagamento e notifica seu serviço de verificação de compras (RevenueCat, Adapty ou sua integração direta)
- Seu serviço de verificação de compras envia um evento de webhook para o Insert Affiliate
- O Insert Affiliate associa a compra à atribuição de afiliado armazenada
- A comissão do afiliado é calculada e registrada
Cada etapa dessa cadeia depende dos webhooks entregando os dados certos no momento certo.
Tipos de Eventos que Você Precisa Tratar
Uma integração completa de webhooks trata vários tipos de eventos além da compra inicial:
Eventos de compra inicial são disparados quando um usuário faz sua primeira assinatura ou compra dentro do app. Esse é o principal evento de conversão que aciona a atribuição de afiliado.
Eventos de renovação são disparados sempre que uma assinatura é renovada. Se o seu modelo de comissão inclui pagamentos recorrentes, os webhooks de renovação acionam cálculos adicionais de comissão.
Eventos de cancelamento são disparados quando um assinante cancela. Eles podem acionar ajustes de comissão ou interromper futuras comissões recorrentes.
Eventos de reembolso são disparados quando uma compra é reembolsada. A maioria dos programas de afiliados recupera as comissões em transações reembolsadas, e esse webhook aciona essa reversão.
Eventos de conversão de teste são disparados quando um teste gratuito é convertido em uma assinatura paga. Para programas que pagam comissão sobre conversões pagas, esse é o gatilho real, não o início do teste.
Integração de Webhook com o RevenueCat
O RevenueCat envia eventos de webhook para todas as mudanças no ciclo de vida da assinatura. Para conectar o RevenueCat ao Insert Affiliate:
- No painel do RevenueCat, navegue até Integrations
- Adicione um endpoint de webhook apontando para a URL de webhook do RevenueCat no Insert Affiliate
- Selecione os eventos que deseja encaminhar: compra inicial, renovação, cancelamento e problemas de cobrança
- Configure os cabeçalhos de autenticação, se necessário
O RevenueCat envia um payload JSON contendo o identificador do cliente, o produto comprado, o valor da receita e os metadados da transação. O Insert Affiliate usa o identificador do cliente para associar a compra ao afiliado que indicou aquele usuário.
Webhooks Diretos da App Store e do Google Play
O Insert Affiliate também integra diretamente com a App Store (via Server Notifications V2) e o Google Play (via Real-Time Developer Notifications). Essas integrações diretas dispensam a necessidade de um serviço terceirizado de gerenciamento de assinaturas.
Para as App Store Server Notifications, configure sua conta do App Store Connect para enviar notificações ao endpoint do Insert Affiliate. As notificações incluem eventos de assinatura em um formato JWT assinado que o Insert Affiliate verifica e processa.
Para o Google Play, configure as Real-Time Developer Notifications por meio do Google Cloud Pub/Sub, com o endpoint do Insert Affiliate como assinante.
Lidando com Falhas de Webhook
Os webhooks podem falhar devido a problemas de rede, indisponibilidade de serviços ou mudanças no formato do payload. Construa resiliência na sua integração:
Lógica de retentativa: A maioria dos provedores de webhook (incluindo o RevenueCat) tenta reenviar automaticamente as entregas que falharam com backoff exponencial. Garanta que seu endpoint receptor retorne os códigos de status HTTP apropriados: 200 para sucesso, 4xx para falhas permanentes e 5xx para falhas temporárias que devem ser retentadas.
Idempotência: Os eventos de webhook podem ser entregues mais de uma vez. Sua lógica de processamento deve lidar com eventos duplicados de forma adequada, verificando os identificadores de transação antes de aplicar mudanças de comissão.
Monitoramento: Configure alertas para falhas na entrega de webhooks. Uma falha silenciosa no seu pipeline de webhooks significa atribuições de afiliados perdidas e, potencialmente, comissões não pagas, o que corrói a confiança dos afiliados.
Testando sua Integração de Webhook
Teste os webhooks em ambientes de sandbox ou staging antes de entrar em produção:
- Faça compras de sandbox em dispositivos de teste
- Verifique se os eventos de webhook chegam ao Insert Affiliate
- Confirme se a correspondência de atribuição funciona corretamente
- Teste casos extremos: reembolsos, expirações de teste, upgrades de assinatura
- Valide os cálculos de comissão em relação aos valores esperados
O painel do Insert Affiliate mostra os eventos de webhook recebidos e seu status de processamento, facilitando a depuração de problemas de integração durante a configuração.
Boas Práticas
Mantenha sua integração de webhook organizada seguindo estes padrões: use exclusivamente endpoints HTTPS, valide as assinaturas dos webhooks para evitar falsificação, processe os eventos de forma assíncrona para evitar problemas de timeout no lado do remetente e registre todos os eventos recebidos para fins de depuração e auditoria.
Uma integração de webhook bem configurada roda silenciosamente em segundo plano, atribuindo com precisão cada compra ao afiliado certo, sem qualquer esforço manual.