Webhooks PagBrasil para Eventos no Klaviyo

Em um cenário de e-commerce e assinaturas, conectar os dados financeiros de uma plataforma de pagamento com as ferramentas de automação de marketing é um diferencial competitivo. Este projeto nasceu da necessidade de integrar a PagBrasil, gateway de pagamentos focado no mercado brasileiro, com o Klaviyo, uma das principais plataformas de marketing automation para e-commerce.

O resultado é uma API serverless, desenvolvida em Python com Flask, que atua como um tradutor e orquestrador: ela recebe webhooks da PagBrasil, enriquece esses dados com informações detalhadas da assinatura e os envia como eventos estruturados para o Klaviyo, permitindo triggers de automação, segmentação avançada e análise de comportamento do cliente.

• Automatizar a comunicação com o cliente baseada no ciclo de vida da assinatura (ativação, pagamento pendente, cancelamento).
• Unificar dados transacionais e de marketing em um único fluxo de dados em tempo real.
• Criar uma ponte serverless e escalável, que opera sob demanda e sem a necessidade de gerenciar infraestrutura.
• Permitir segmentação avançada no Klaviyo, utilizando propriedades como status da assinatura, produto adquirido e valor do pedido.

Fluxo de Dados

1. Webhook Recebido: A PagBrasil envia um payload JSON com o identificador da assinatura (subscription).
2. Consulta à PagBrasil: A API utiliza o PAGBRASIL_SECRET e PAGBRASIL_PBTOKEN para autenticar e buscar os dados completos da assinatura.
3. Mapeamento de Dados: Códigos de status e métodos de pagamento são convertidos em nomes legíveis.
4. Envio ao Klaviyo: Um novo evento é criado na plataforma, contendo as propriedades mapeadas.
5. Resposta ao Webhook: A API retorna um status 200 para a PagBrasil, confirmando o processamento.

Exemplo de Saída (Evento Klaviyo)

O evento enviado ao Klaviyo contém propriedades como billing_cycle, cancellation_date, product_sku, order_status e payment_method, permitindo uma segmentação rica e precisa.

O projeto foi projetado para ser deployado de forma simples e rápida no Google Cloud Run, uma plataforma serverless que gerencia automaticamente a infraestrutura.

Comando de Deploy Exemplo

gcloud run deploy pagbrasil-webhook \
  --source . \
  --platform managed \
  --region us-central1 \
  --allow-unauthenticated \
  --set-env-vars "PAGBRASIL_SECRET=... ,PAGBRASIL_PBTOKEN=... ,KLAVIYO_API_KEY=..."

As variáveis de ambiente gerenciam todas as credenciais sensíveis, garantindo a segurança da aplicação.

• Debugging Remoto: Rastrear erros em um ambiente serverless exigiu o uso intensivo dos logs do Cloud Run, o que reforçou a importância de uma boa estratégia de logging.
• Mapeamento de Dados: A necessidade de mapear diversos códigos de status da PagBrasil em textos para o Klaviyo me fez aprofundar na documentação de ambas as APIs, garantindo uma integração sem fricção.
• Arquitetura Orientada a Eventos: Entender o fluxo de webhooks e eventos foi crucial para projetar uma aplicação que atua como um "tradutor" entre dois sistemas distintos.

A API PagBrasil → Klaviyo demonstra como a integração entre sistemas pode gerar valor real para o negócio. Ela transforma dados brutos em ações de marketing personalizadas, escaláveis e baseadas em dados. Este projeto não apenas resolve um problema específico, mas também serve como um exemplo de boas práticas para integrações serverless, consolidando meu conhecimento em Python, arquitetura de APIs e automação de marketing.

Exemplo de Projeto no Github.