Parâmetros de postback de offerwall: Lootably, AdGate Media, CPX Research e BitLabs
Todo offerwall chama o seu servidor quando um usuário conclui uma oferta, e cada um dá um nome diferente para a mesma coisa. O usuário é {userID} em um, {s1} em outro e [%USER:UID%] num terceiro. Este guia coloca lado a lado os parâmetros de postback dos quatro offerwalls mais usados por sites de recompensas e GPT, com a forma como cada um avisa de um estorno e como conferir se um postback é verdadeiro.
Resposta curta
A Lootably envia {userID}, {transactionID}, {currencyReward}, {revenue}, {ip} e {status}; a AdGate Media usa {s1} para o usuário, {points}, {payout} e {state}; a CPX Research envia {user_id}, {trans_id}, {amount_local}, {amount_usd} e {status}; a BitLabs usa [%USER:UID%], [%TX%], [%VALUE:CURRENCY%] e [%VALUE:USD%]. Credite cada transação uma única vez, verifique o hash e trate os estornos.
- Sinal de estorno
- Lootably: status 0. AdGate: state "rejected". CPX Research: status 2. BitLabs: tipo RECONCILIATION.
- Assinaturas
- Lootably: SHA-256. BitLabs: HMAC SHA-1 da URL completa. CPX Research: uma macro de hash seguro. AdGate: nenhuma, lista de IPs permitidos.
- A mesma ideia, quatro nomes
- O ID do usuário é {userID}, {s1}, {user_id} ou [%USER:UID%].
- Conferido com
- A documentação de postback de cada offerwall, outubro de 2026.
Por que os nomes importam
Um postback é uma requisição do servidor do offerwall para o seu. Ele diz que um usuário concluiu uma oferta e quanto creditar. O seu endpoint lê alguns valores: quem é o usuário, qual é a transação, quantos pontos dar e, às vezes, o IP de onde a oferta começou. Se um deles for lido do parâmetro errado, o usuário recebe o valor errado, em dobro ou nunca.
Cada offerwall deixa você montar a URL de postback: você escolhe os nomes dos seus parâmetros e coloca as macros do offerwall como valores, por exemplo ?user={userID}&tx={transactionID}. As tabelas abaixo listam as macros. Os nomes dos seus parâmetros podem ser quaisquer.
Para revisar uma URL que você já tem, cole no verificador de postback gratuito: ele marca cada macro que o offerwall não vai preencher (maiúsculas trocadas, o nome de outro offerwall, chaves codificadas na URL) e o que falta no postback.
Lootably
| Macro | O que traz |
|---|---|
| {userID} | O usuário que concluiu a oferta |
| {transactionID} | O ID desta conversão na Lootably |
| {currencyReward} | A recompensa na sua moeda, conforme o placement |
| {revenue} | O que você ganhou, em USD |
| {ip} | O IP do usuário ao iniciar a oferta |
| {offerID} / {offerName} | A oferta |
| {goalID} / {goalName} | A meta, em ofertas de várias etapas |
| {status} | 1 para uma conversão, 0 para um chargeback |
| {hash} | Assinatura SHA-256 |
O hash é o sha256 de userID, ip, revenue e currencyReward seguidos da sua chave secreta de postback, concatenados nessa ordem. A Lootably documenta status 0 para chargebacks, mas avisa que por enquanto só envia postbacks com status 1: deixe o tratamento de estornos pronto sem depender dele ainda.
AdGate Media
| Macro | O que traz |
|---|---|
| {s1} | O seu ID de usuário (até 255 caracteres) |
| {conversion_id} | O ID da conversão |
| {points} | Os pontos a creditar, decimais ou inteiros |
| {payout} | O que você ganhou, em USD |
| {offer_id} / {vc_title} | O ID da oferta e o título exibido no mural |
| {session_ip} | O IP do usuário que concluiu a oferta |
| {state} | approved, rejected ou pending |
| {status} | Obsoleto: a AdGate agora pede {state} no lugar |
O exemplo da própria AdGate é ?conversion_id={conversion_id}&user_id={s1}&point_value={points}&usd_value={payout}&offer_title={vc_title}. Adicione {state}: sem ele, a AdGate só envia conversões aprovadas; com ele, uma conversão estornada chega de novo com state rejected e o mesmo ID de conversão, e você encontra o crédito original para retirá-lo.
A AdGate não assina os postbacks. Ela publica os IPs de onde eles vêm e pede uma URL de postback que só a AdGate chame, então permita apenas esses endereços nesse endpoint.
CPX Research
| Macro | O que traz |
|---|---|
| {user_id} | O seu ID de usuário |
| {trans_id} | O ID da transação |
| {amount_local} | A recompensa na sua moeda |
| {amount_usd} | O que você ganhou, em USD |
| {offer_ID} | A pesquisa ou oferta |
| {ip_click} | O IP do usuário no clique |
| {subid} / {subid_2} | Os seus próprios valores de rastreamento |
| {status} | 1 concluída, 2 cancelada |
| {secure_hash} | Assinatura para verificar o postback |
Um postback típico da CPX é ?status={status}&trans_id={trans_id}&user_id={user_id}&amount_local={amount_local}&amount_usd={amount_usd}&hash={secure_hash}&ip_click={ip_click}. Atenção: um cancelamento é status 2, não 0. Um código feito para outro offerwall que só verifica o 0 vai creditar os cancelamentos da CPX como pesquisas novas.
BitLabs
| Macro | O que traz |
|---|---|
| [%USER:UID%] | O seu ID de usuário (até 255 caracteres) |
| [%TX%] | O ID da transação, para não creditar duas vezes |
| [%VALUE:CURRENCY%] | A recompensa na moeda do seu app |
| [%VALUE:USD%] | O que você ganhou, em USD |
| [%USER:IP_ADDRESS%] | O IP do usuário |
| [%OFFER:ID%] / [%OFFER:NAME%] | A oferta |
| [%ACTIVITY:TYPE%] | COMPLETE, SCREENOUT, RECONCILIATION ou START_BONUS |
| [%REF%] | Numa reconciliação, a transação original que é retirada |
Integrações antigas usam as formas curtas [%UID%], [%VAL%] e [%RAW%]; a documentação atual da BitLabs usa os nomes acima. Um estorno chega como callback do tipo RECONCILIATION: adicione [%REF%] para saber qual recompensa ele estorna.
A BitLabs anexa um hash a cada callback: um HMAC SHA-1 da URL completa, em hexadecimal, com a chave secreta do seu app. Como ele cobre a URL inteira, verifique antes de ler ou alterar qualquer coisa e use a URL exatamente como chegou.
O que todo endpoint de postback deve fazer
- Verifique a assinatura com o método daquele offerwall e recuse a requisição se não bater.
- Credite cada ID de transação uma única vez. Os offerwalls repetem o envio quando o seu servidor demora; um índice único no ID da transação torna a repetição inofensiva.
- Trate os estornos. Saiba qual valor significa estorno em cada offerwall (status 0 na Lootably, state rejected na AdGate, status 2 na CPX Research, tipo RECONCILIATION na BitLabs) e retire a recompensa, ou segure se ela ainda não foi sacada.
- Responda rápido com a resposta que o offerwall espera e deixe o trabalho lento para depois.
- Confira a pessoa, não só a requisição. Um postback bem assinado ainda pode pagar uma fazenda: dez contas no mesmo celular, uma VPN para parecer dos EUA, uma oferta concluída mais rápido do que alguém conseguiria jogar.
Esse último ponto é o que nenhuma assinatura cobre. Veja como detectar multicontas num site de recompensas e como barrar fraude com VPN em offerwalls para ver como é a fraude que chega com a assinatura certa.
Teste o seu endpoint antes de ir ao ar
Quatro requisições dizem se um endpoint está pronto. Envie você mesmo com curl ou pelo navegador, com um usuário de teste e valores inventados:
- Uma conversão normal. O usuário de teste recebe o crédito uma única vez, na sua moeda.
- A mesma requisição de novo. Nada muda: o ID da transação já existe, e o seu endpoint continua respondendo com sucesso para o offerwall parar de repetir.
- Um estorno com o valor de status daquele offerwall. A recompensa é retirada ou retida, e o histórico da conta mostra o motivo.
- Um hash errado. A requisição é recusada e nada é creditado.
Se alguma das quatro se comportar de outro jeito, corrija antes de ativar o offerwall: cada uma é um caminho por onde vaza dinheiro de verdade.
Conferir cada postback sem programar
O relay de postback da CashoutGuard fica entre o offerwall e o seu endpoint. Você cola a sua URL de postback atual, recebe uma nova para colocar no offerwall, e cada conversão é avaliada para VPN, emuladores, celulares na nuvem e contas ligadas antes de chegar até você. Ele lê as macros acima mesmo quando os seus parâmetros têm nomes curtos como ?a={userID}&b={transactionID}, e aprende com os estornos enviados com um valor de status, então cada chargeback melhora a próxima decisão.