O que são os Callbacks de Aplicação no Post Affiliate Pro?
Saiba como funcionam os Callbacks de Aplicação no Post Affiliate Pro. Descubra gatilhos de eventos personalizáveis para vendas, leads e cadastros de afiliados c...
9
Disponível em:
Post Affiliate Pro , Post Affiliate Pro Ultimate , Post Affiliate Network
O que são Webhooks e Callbacks?
Webhooks (também chamados de Application Callbacks ou Postback URLs) são notificações HTTP automatizadas que o Post Affiliate Pro envia para sistemas externos quando eventos específicos ocorrem. Em vez de constantemente consultar por atualizações, seus sistemas conectados recebem notificações instantâneas no momento em que algo acontece no seu programa de afiliados.
Este recurso é essencial para:
- Integração com CRM - Atualizar automaticamente seu banco de dados de clientes quando vendas ocorrem
- Automação de Email - Acionar sequências de email baseadas em ações de afiliados
- Sistemas Contábeis - Sincronizar dados de transações com seu software financeiro
- Dashboards Personalizados - Construir dashboards de relatórios em tempo real
- Rastreamento de Terceiros - Notificar plataformas de rastreamento externas sobre conversões
Tipos de Webhooks
O Post Affiliate Pro suporta dois tipos principais de webhooks:
Webhooks de Rastreamento de Vendas
Esses webhooks são acionados por eventos relacionados a transações:
| Evento de Acionamento | Descrição |
|---|---|
| Na Criação | Dispara imediatamente quando uma nova transação (venda, ação, lead) é registrada |
| Na Aprovação | Dispara quando uma transação pendente é aprovada |
| Na Recusa | Dispara quando uma transação é recusada |
| No Reembolso/Chargeback | Dispara quando um reembolso ou chargeback é processado |
Você pode configurar um único webhook para disparar em múltiplos eventos, ou criar webhooks separados para cada tipo de evento.
Webhooks de Cadastro de Afiliados
Esses webhooks são acionados por eventos de registro de afiliados:
| Evento de Acionamento | Descrição |
|---|---|
| No Cadastro | Dispara imediatamente quando um novo afiliado completa o formulário de cadastro |
| Na Aprovação | Dispara quando um afiliado pendente é aprovado por um comerciante |
Tipos de Requisição
O Post Affiliate Pro suporta três tipos de requisição HTTP para webhooks:
Requisição GET
Parâmetros são anexados à URL como parâmetros de query string.
https://seu-sistema.com/webhook?transactionid=abc123&commission=50.00&orderid=PED-456
Requisição POST (Form-Urlencoded)
Parâmetros são enviados no corpo da requisição usando codificação de formulário padrão.
Content-Type: application/x-www-form-urlencoded
transactionid=abc123&commission=50.00&orderid=PED-456
Requisição POST JSON
Parâmetros são enviados como um objeto JSON no corpo da requisição.
Content-Type: application/json
{"transactionid": "abc123", "commission": "50.00", "orderid": "PED-456"}
Variáveis Disponíveis para Webhooks de Vendas
Você pode usar variáveis dinâmicas em suas URLs de webhook que são automaticamente substituídas por valores reais. Use o formato ${#nomevariavel#} para incluir uma variável.
Dados de Transação
| Variável | Descrição |
|---|---|
${#transactionid#} | Identificador único da transação |
${#visitorid#} | ID do visitante (cookie de rastreamento) |
${#commission#} | Valor da comissão |
${#totalcost#} | Valor total do pedido |
${#fixedcost#} | Valor de custo fixo |
${#orderid#} | ID do pedido do seu sistema e-commerce |
${#productid#} | ID do produto |
${#dateinserted#} | Data e hora de criação da transação |
${#dateapproved#} | Data e hora de aprovação da transação |
${#tier#} | Nível de comissão |
${#status#} | Status da transação (Aprovado, Pendente, Recusado) |
${#statuscode#} | Código de status (A, P, D) |
${#type#} | Tipo de transação (Venda, Ação, etc.) |
Dados de Campanha e Banner
| Variável | Descrição |
|---|---|
${#campaignid#} | Identificador da campanha |
${#campaignname#} | Nome da campanha |
${#bannerid#} | Identificador do banner |
${#channel#} | Nome do canal |
${#channel_code#} | Código do canal |
${#coupon_code#} | Código de cupom usado |
Dados do Afiliado
| Variável | Descrição |
|---|---|
${#userid#} | ID de usuário do afiliado |
${#refid#} | ID de referência do afiliado |
Dados de Clique
| Variável | Descrição |
|---|---|
${#firstclicktime#} | Timestamp do primeiro clique |
${#firstclickreferer#} | URL de referência do primeiro clique |
${#firstclickip#} | Endereço IP do primeiro clique |
${#firstclickdata1#} | Dado personalizado 1 do primeiro clique |
${#firstclickdata2#} | Dado personalizado 2 do primeiro clique |
${#lastclicktime#} | Timestamp do último clique |
${#lastclickreferer#} | URL de referência do último clique |
${#lastclickip#} | Endereço IP do último clique |
${#lastclickdata1#} | Dado personalizado 1 do último clique |
${#lastclickdata2#} | Dado personalizado 2 do último clique |
Dados Personalizados de Transação
| Variável | Descrição |
|---|---|
${#saledata1#} | Campo de dados personalizado 1 da transação |
${#saledata2#} | Campo de dados personalizado 2 da transação |
${#saledata3#} | Campo de dados personalizado 3 da transação |
${#saledata4#} | Campo de dados personalizado 4 da transação |
${#saledata5#} | Campo de dados personalizado 5 da transação |
Dados Geográficos e Técnicos
| Variável | Descrição |
|---|---|
${#ip#} | Endereço IP do cliente |
${#countrycode#} | Código do país baseado no IP |
${#refererurl#} | URL de referência |
Dados de Moeda
| Variável | Descrição |
|---|---|
${#originalcurrency#} | Nome da moeda original |
${#originalcurrencyvalue#} | Valor na moeda original |
${#originalcurrencyrate#} | Taxa de câmbio usada |
Notas
| Variável | Descrição |
|---|---|
${#merchantnote#} | Nota visível para o afiliado |
${#systemnote#} | Nota visível apenas para o comerciante |
${#actionName#} | Nome do tipo de comissão de ação |
${#actionCode#} | Código do tipo de comissão de ação |
Variáveis Disponíveis para Webhooks de Cadastro
Para webhooks de cadastro de afiliados, você pode usar variáveis de perfil do afiliado:
| Variável | Descrição |
|---|---|
${#username#} | Email/username do afiliado |
${#firstname#} | Primeiro nome do afiliado |
${#lastname#} | Sobrenome do afiliado |
${#name#} | Nome completo (primeiro + sobrenome) |
${#userId#} | ID de usuário do afiliado |
| Campos personalizados | Qualquer campo de perfil personalizado pelo seu código |
Suporte Multinível
Por padrão, webhooks são executados apenas para comissões de nível 1 (diretas). Você pode habilitar a opção “Executar para cada nível” para acionar webhooks para todos os níveis em estruturas de comissão multinível.
Isso é útil quando:
- Você precisa rastrear comissões em todos os níveis da sua hierarquia de afiliados
- Seu sistema externo precisa saber sobre ganhos de sub-afiliados
- Você está construindo relatórios abrangentes que incluem todos os níveis de comissão
Opções de Filtragem de Webhooks
Você pode configurar webhooks para serem mais específicos:
Por Tipo de Comissão
Limite o webhook a um tipo específico de comissão (ex.: apenas para comissões de ação “Vendas Premium”).
Por Afiliado
Crie webhooks que disparam apenas para um afiliado específico. Isso é útil para:
- Afiliados que usam seus próprios sistemas de rastreamento
- Integrações especiais para afiliados de alto desempenho
- Testar webhooks com um único afiliado antes de expandir
Por Conta (Modo Rede)
No Post Affiliate Network, você pode criar webhooks específicos por conta.
Log e Monitoramento de Webhooks
O Post Affiliate Pro mantém um log abrangente de todas as execuções de webhooks, acessível no painel do comerciante em Ferramentas > Log de Callbacks.
O log mostra:
- ID do Log - Identificador único para cada execução de webhook
- ID do Callback - Qual configuração de webhook foi usada
- URL da Requisição - A URL completa que foi chamada (com variáveis substituídas)
- Data de Criação - Quando o webhook foi enfileirado
- Última Tentativa - Quando a última tentativa de execução foi feita
- Número de Tentativas - Quantas vezes o sistema tentou executar
- Status - Pendente, Enviado ou Erro
- Mensagem de Erro - Detalhes se o webhook falhou
Tentativa Automática
Se um webhook falhar (ex.: seu servidor está temporariamente indisponível), o Post Affiliate Pro automaticamente tentará novamente a requisição. Isso garante entrega confiável mesmo durante interrupções temporárias.
Retenção de Log
Logs de webhooks são automaticamente limpos após um número configurável de dias (padrão: 60 dias). Você pode ajustar isso em Configuração > Recursos > Application Callbacks.
Gerenciamento de Webhooks
Fluxo de Aprovação
Por padrão, webhooks criados por afiliados requerem aprovação do comerciante antes de se tornarem ativos. Comerciantes podem:
- Habilitar aprovação automática - Aprovar automaticamente todos os novos webhooks
- Revisar manualmente - Aprovar ou recusar cada webhook individualmente
Gerenciamento de Status
Webhooks têm três status possíveis:
- Aprovado - Ativo e será executado quando acionado
- Pendente - Aguardando aprovação do comerciante
- Recusado - Rejeitado e não será executado
Comerciantes podem alterar o status do webhook a qualquer momento da tela de gerenciamento de webhooks.
Notificações por Email
O Post Affiliate Pro pode enviar notificações por email para eventos relacionados a webhooks:
Notificações ao Comerciante
- Novo webhook criado por afiliado
Notificações ao Afiliado (Opcional)
- Status do webhook alterado (aprovado/recusado)
- Webhook modificado pelo comerciante
- Webhook excluído pelo comerciante
Essas notificações podem ser habilitadas ou desabilitadas em Configuração > Notificações por Email.
Exemplos de Casos de Uso
1. Integração com CRM
Envie dados de novas vendas para seu CRM quando uma transação é aprovada:
https://crm.exemplo.com/api/sales?customer_order=${#orderid#}&value=${#totalcost#}&affiliate=${#refid#}
2. Notificação no Slack
Notifique o canal da sua equipe quando um novo afiliado se cadastra:
https://hooks.slack.com/services/xxx/yyy?text=Novo+afiliado:+${#firstname#}+${#lastname#}
3. Gatilho de Plataforma de Email
Adicione clientes a uma sequência de email após compra:
POST https://email.exemplo.com/api/subscribers
Body: {"email": "${#saledata1#}", "purchase_value": "${#totalcost#}"}
4. Sincronização com Software Contábil
Registre pagamentos de comissão no seu sistema contábil:
https://contabilidade.exemplo.com/webhook?affiliate_id=${#userid#}&commission=${#commission#}&order=${#orderid#}
Como Configurar um Webhook
- Faça login no seu Painel do Comerciante
- Navegue até Configuração > Recursos
- Ative o recurso Application Callbacks
- Vá em Campanhas > [Selecione Campanha] > Callbacks ou o gerenciador global de callbacks
- Clique em Adicionar Novo Callback
- Configure:
- Nome - Um nome descritivo para o webhook
- Tipo - Rastreamento de Vendas ou Cadastro de Afiliado
- Execução - Quando acionar (na criação, aprovação, recusa, reembolso)
- Tipo de Requisição - GET, POST ou POST JSON
- URL - Seu endpoint com variáveis
- Executar para cada nível - Sim/Não
- Salve o webhook
Considerações de Segurança
- Use endpoints HTTPS para transmissão segura de dados
- Considere adicionar um parâmetro secreto para verificar a origem do webhook
- Implemente limitação de taxa no seu endpoint receptor
- Valide dados recebidos antes de processar
- Mantenha logs de webhooks para fins de auditoria
Recursos Relacionados
- Rastreamento S2S - Rastreamento server-to-server para conversões precisas
- API - Acesso programático completo ao Post Affiliate Pro
- API v3 - API RESTful moderna com OAuth 2.0
