Atribuição em Tempo Real Através de Webhooks
Webhooks são callbacks HTTP que notificam a Insert Affiliate no momento em que uma compra ocorre no seu aplicativo. Essa cadeia de notificação em tempo real garante que os afiliados sejam creditados instantaneamente quando os usuários que eles indicaram fazem compras dentro do aplicativo, sem processamento em lote, sem atrasos e sem eventos perdidos.
A Arquitetura de Webhook
O fluxo em tempo real funciona da seguinte forma:
- O usuário faz uma compra no seu aplicativo
- A loja de aplicativos processa o pagamento (Apple ou Google)
- Seu serviço de verificação de compras (RevenueCat, Adapty ou integração direta com a loja) recebe a notificação da compra
- O serviço de verificação envia um webhook para o endpoint da Insert Affiliate
- A Insert Affiliate processa o evento, relacionando-o a uma atribuição de afiliado e calculando a comissão
- O painel do afiliado é atualizado mostrando a nova conversão e os ganhos
Toda essa cadeia se completa em segundos.
Tipos de Evento a Configurar
Eventos de Assinatura
- INITIAL_PURCHASE: Primeiro pagamento da assinatura (evento de conversão principal)
- RENEWAL: Pagamento recorrente, que aciona comissão adicional para modelos recorrentes
- CANCELLATION: Usuário cancelou, o que interrompe o acúmulo de comissões futuras
- BILLING_ISSUE: Falha no pagamento, então a assinatura pode estar em período de carência
- PRODUCT_CHANGE: Usuário fez upgrade ou downgrade, então a comissão é ajustada
- EXPIRATION: Assinatura totalmente expirada após o período de carência
Eventos de Compra Única
- NON_RENEWING_PURCHASE: Desbloqueio único ou compra não consumível
- CONSUMABLE_PURCHASE: IAP consumível (deve ser reportado através do SDK, não por webhooks da loja)
Eventos de Reembolso
- REFUND: Compra reembolsada, o que aciona a reversão da comissão
Melhores Práticas de Confiabilidade
Garanta a Entrega
- Retorne o status 200 imediatamente ao receber o webhook, antes do processamento
- Processe de forma assíncrona: confirme o recebimento primeiro e, depois, trate a lógica de negócio
- Monitore as taxas de entrega: verifique os logs de entrega de webhook do seu serviço de verificação de compras semanalmente
Lide com Falhas
- Configuração de novas tentativas: A maioria dos remetentes de webhook tenta novamente as entregas com falha usando backoff exponencial. Garanta que seu endpoint lide com as novas tentativas de forma adequada.
- Idempotência: Processe cada evento exatamente uma vez. Use o ID da transação para detectar e ignorar entregas duplicadas.
- Alertas: Configure notificações para falhas na entrega de webhooks para que você possa responder antes que os afiliados percebam comissões faltantes.
Segurança
- Verifique as assinaturas: A maioria dos provedores de webhook assina seus payloads. Verifique as assinaturas para evitar eventos falsificados.
- Use HTTPS: Todos os endpoints de webhook devem usar criptografia HTTPS.
- Restrinja o acesso: Se possível, inclua na lista de permissões os endereços IP do remetente do seu webhook.
Webhooks Diretos da Loja vs. Terceiros
Através do RevenueCat/Adapty (recomendado):
- Um único endpoint de webhook lida com iOS e Android
- Formato de evento normalizado entre as plataformas
- Monitoramento de novas tentativas e de entrega integrado
- Menos complexidade de configuração
Diretamente da Apple/Google:
- Apple Server Notifications V2: JWTs assinados com eventos do ciclo de vida da assinatura
- Google Real-Time Developer Notifications via Cloud Pub/Sub
- Mais configuração, mas sem dependência de terceiros
- Formatos diferentes exigem lógica de tratamento separada
Testando o Pipeline de Webhook
- Compras em sandbox: Faça compras de teste e verifique se os webhooks chegam à Insert Affiliate
- Cobertura de tipos de evento: Teste cada tipo de evento: compra, renovação, cancelamento, reembolso
- Tempo: Verifique se os eventos chegam em segundos, não em minutos
- Correspondência de atribuição: Confirme que a compra corresponde ao afiliado correto
- Cálculo da comissão: Verifique se o valor da comissão está correto
O painel da Insert Affiliate mostra os eventos de webhook recebidos e seu status de processamento, tornando simples verificar se o pipeline está funcionando corretamente antes e depois do lançamento.