Pular para o conteúdo
Abrir o Leadz

Postbacks

Receba conversões de redes de afiliados, corretoras e trackers por um endereço com parâmetros e ligue cada evento ao contato certo.

No Leadz:ConexõesWebhooks e Postbacks Abrir esta tela
Nesta página

Um postback é um aviso que outra plataforma manda para o Leadz chamando um endereço com os dados dentro dele, como ?click_id=42&event=deposit. É o formato usado por redes de afiliados, corretoras e trackers para avisar de um cadastro, um depósito ou uma venda. No Leadz, cada postback pode atualizar um contato que já existe, registrar uma negociação e iniciar um funil.

#Postback ou webhook?

Postback Webhook
Como os dados chegam Como parâmetros no endereço No corpo da requisição, em JSON
Método usual GET POST
Quem costuma usar Redes de afiliados, corretoras, trackers Formulários, plataformas de venda, ferramentas de automação
Cria contato novo Não. Só atualiza um contato que já existe Sim
Resposta padrão Texto OK JSON

Se a plataforma envia JSON, use um webhook de entrada.

#Criar o postback

  1. Abra Conexões › Webhooks e Postbacks.
  2. Clique em Nova URL e escolha Postback.
  3. Preencha Nome (por exemplo, «Rede XYZ — conversão») e, se quiser, Descrição (opcional).
  4. Clique em Criar postback.

O postback nasce sem parâmetros. Você declara os que a plataforma envia, de um dos dois jeitos abaixo.

#Declarar os parâmetros

#A partir de um postback recebido

É o jeito mais rápido, porque você não precisa adivinhar os nomes.

  1. Copie o endereço pelo botão Copiar e cadastre na plataforma de origem.
  2. Dispare um postback de teste pela plataforma.
  3. Em Eventos recebidos, clique no evento e depois em Configurar a partir deste evento.
  4. Marque os parâmetros que quer usar.
  5. Em Grava em, escolha para onde cada um vai no contato. Para guardar um dado que o Leadz não tem, escolha + Criar campo personalizado….
  6. Marque Encontra contato no parâmetro que identifica a pessoa.
  7. Clique em Aplicar.

Um parâmetro que chegou sem valor continua na lista, com o aviso «veio vazio neste evento». Você pode declará-lo mesmo assim.

#À mão

  1. Clique em Configurar no cartão do endereço.
  2. Em Parâmetros da URL, clique em Novo parâmetro.
  3. Preencha Campo (o nome que você vai ver na tela) e Parâmetro na URL (o nome exato que a plataforma envia, como click_id).
  4. Marque Obrigatório se o postback não vale sem ele.
  5. Clique em Salvar configuração.

Cada parâmetro tem uma chave para ligar e desligar. Parâmetro desligado sai do endereço e é ignorado na chegada.

#Montar o endereço na plataforma

O cartão URL pública · GET mostra o endereço com os parâmetros ativos e o token. Use o que a tela mostrar. O formato é este:

https://SEU-ENDERECO/api/webhooks/ID-DA-CONTA/rede-xyz?click_id=&txid=&payout=&event=&token=SEU-TOKEN

Na plataforma de origem, preencha depois de cada = a variável que ela oferece. O nome das variáveis muda de plataforma para plataforma; consulte a ajuda dela. Um endereço pronto fica parecido com este:

https://SEU-ENDERECO/api/webhooks/ID-DA-CONTA/rede-xyz?click_id={click_id}&txid={transaction_id}&payout={payout}&event=deposit&token=SEU-TOKEN

Se a plataforma envia por POST, troque Método HTTP para POST — query + body na configuração.

#Identificar o contato

O postback não cria contato. Ele procura um contato que já existe e grava os dados nele. Para isso, ligue Vincular ao contato na configuração e diga qual parâmetro identifica a pessoa.

Em Parâmetros e destinos, cada linha tem três colunas: Parâmetro na URL, Grava em e Encontra contato. Você pode identificar por:

  • Telefone, WhatsApp ou E-mail, quando a plataforma envia um deles.
  • ID do contato (#1, #2…), quando você passa o número do contato no link de divulgação e a plataforma devolve esse número no postback.
  • ID externo (da origem) ou um campo personalizado, quando a plataforma tem um código próprio para a pessoa e esse código já está gravado no contato.

Ainda na mesma seção:

  • Tag ao vincular (opcional) aplica uma tag toda vez que o postback encontra o contato. Use nomes como cadastrou ou deposito.
  • Tags extras (opcional) aplica outras tags do seu catálogo.
  • O contato encontrado também recebe a tag afiliado.

#Guardar um dado em campo personalizado

Em Grava em, escolha um campo personalizado ou crie um na hora com + Criar campo personalizado…. Serve para guardar comissão, oferta, cupom ou qualquer outro parâmetro da plataforma.

Para registrar uma negociação no contato, mande o parâmetro do valor para Valor (ou Valor em centavos, se a plataforma envia em centavos).

#Testar

  1. Copie o endereço e preencha valores de teste depois de cada =. Em click_id, phone ou email, use um dado de um contato que já existe.
  2. Abra o endereço no navegador. A resposta deve ser OK.
  3. Volte ao Leadz e confira o evento em Eventos recebidos. Verde com Contato vinculado quer dizer que o contato foi encontrado.
  4. Clique no evento para ver a tabela Parâmetros do postback, com o valor de cada um e a coluna Vai para.

#Usar o postback em um funil

No editor de funil, adicione o gatilho Postback recebido. Escolha o postback ou deixe Qualquer postback. Em Filtrar evento (opcional), escreva o valor do parâmetro de evento que deve iniciar o funil, como deposit. O bloco Aguardar Evento também pode esperar por um postback no meio do funil.

#Resposta, segurança e deduplicação

Essas opções ficam em Configurar, na seção Resposta, segurança e deduplicação.

  • Resposta ao servidor de afiliados. O padrão é Padrão do mercado — HTTP 200 + "OK". Redes de afiliados esperam essa resposta para não reenviar. Há também HTTP 200 sem corpo, HTTP 200 + "success", HTTP 200 + JSON e Personalizado.
  • Autenticação. O token vai no próprio endereço, em ?token=. Você pode mudar o Nome do parâmetro se a plataforma exigir outro.
  • Deduplicar por ID da transação. Vem ligado. Plataformas reenviam o mesmo postback quando não recebem resposta a tempo; sem deduplicar, o reenvio conta como segunda conversão. Escolha o parâmetro em Parâmetro usado na deduplicação.
  • Limite de envio. Cada origem pode enviar até 120 requisições por minuto.

O token é retirado dos dados antes de o evento ser guardado. Quem abre o evento na tela não vê o token.

#Problemas comuns

O evento fica como «Sem ação no CRM» e o parâmetro do telefone veio vazio

A plataforma mandou phone= sem valor. Sem o dado, o Leadz não tem como achar o contato. Identifique por outro parâmetro que venha preenchido (e-mail, ID do contato (#1, #2…) ou um código da origem) ou peça à plataforma para enviar o telefone.

Aparece «Contato não foi gravado.» com «Nenhum contato encontrado com essa regra de vínculo»

O parâmetro chegou, mas nenhum contato tem aquele valor. Confira se o contato já existe e se o dado está igual. Lembre que o postback não cria contato novo.

Aparece «Nenhum parâmetro reconhecido neste evento.»

O postback chegou, mas os nomes enviados não foram declarados. Use Configurar a partir deste evento para declarar os parâmetros que vieram.

A plataforma recebe «Parâmetro(s) obrigatório(s) ausente(s)»

Um parâmetro marcado como Obrigatório não veio. Corrija o endereço na plataforma ou desmarque Obrigatório.

A plataforma recebe «Token de postback inválido»

O endereço foi cadastrado sem o token= ou com o token antigo. Copie o endereço de novo pelo botão Copiar. Se você clicou em Gerar novo token, o endereço anterior parou de valer.

A plataforma recebe «Este postback está configurado apenas para GET»

A plataforma está enviando por POST. Troque Método HTTP para POST — query + body.

O mesmo evento chegou duas vezes e só um apareceu

É a deduplicação. Dois postbacks com o mesmo ID de transação contam como um só. A plataforma recebe OK nos dois.

O valor da comissão foi gravado 100 vezes maior

O parâmetro vem em centavos e foi mapeado para Valor. Mapeie para Valor em centavos.

#Veja também

Este artigo ajudou?

Mais em Integrações

Ver os 8 artigos