How to Set Up Postback for CPAlead.com Offerwall: A Simple Guide

Author: CPAlead

Updated Friday, September 20, 2024 at 8:34 AM CDT

How to Set Up Postback for CPAlead.com Offerwall: A Simple Guide

Setting up a postback is the most reliable way to reward users automatically when they complete offers in your CPAlead Offerwall. Instead of checking conversions manually, CPAlead sends a server-to-server request to your endpoint each time a qualifying lead is created.

The safest setup is simple: pass your own user or transaction reference in {subid}, store {lead_id} so retries do not double-credit the same conversion, and reward from {payout}. In most cases, that is all you need to launch.

What a Publisher Postback Actually Does

When a user clicks your CPAlead tracking URL and completes an offer, CPAlead can call your server with conversion data. That lets your app, website, or game reward the user automatically without anyone needing to review conversions by hand.

Reward users automatically: credit points, balance, coins, or premium access as soon as a conversion is recorded.
Keep your own ledger: store each conversion in your own database for finance, support, and analytics.
Avoid duplicate rewards: use CPAlead’s unique {lead_id} to ignore retries safely.
Track richer context: include optional values like country, IP, device IDs, or extra subids if your workflow needs them.

Step 1: Pass Your Own Reference in the Offerwall URL

Before you worry about the postback URL, make sure the original CPAlead tracking URL contains your own identifier in subid. This can be a user ID, username, wallet ID, session key, or any internal reference you use to know which user should be rewarded.

https://your-tracking-domain/view.php?id=1234&pub=1234&subid=USER_123

If you need extra context, you can also pass subid2 and subid3. For example, some publishers use subid for the user ID, subid2 for the app placement, and subid3 for a campaign or A/B test label.

Step 2: Start with a Clean, Reliable Postback URL

A lot of postback setups fail because they start too wide. Keep your first version small and dependable. This is a strong starting pattern for most CPAlead publishers:

https://example.com/postback/cpalead.php?subid={subid}&lead_id={lead_id}&campaign_id={campaign_id}&campaign_name={campaign_name}&payout={payout}&password={password}

This version gives you the fields most publishers actually need: who to reward, which lead converted, which offer converted, how much it paid, and a shared secret to verify the request.

Step 3: Understand the Recommended Macros

{subid}: your own user ID or transaction reference. This tells your system who should receive the reward.
{lead_id}: CPAlead’s unique conversion ID. This is the best field for duplicate protection and retry safety.
{campaign_id}: the CPAlead offer or campaign ID.
{campaign_name}: the CPAlead offer or campaign name.
{payout}: the payout amount for the conversion. Most publishers should use this as the reward input.
{password}: your saved postback secret, which your endpoint should validate before crediting the user.

Optional macros include {subid2}, {subid3}, {country_iso}, {ip_address}, {idfa}, {gaid}, and {gateway_id}. CPAlead also supports compatibility aliases such as {offer_id}, {offer_name}, {transaction_id}, {amount}, {ip}, and {country_code} if your existing endpoint expects those names.

One important note: do not build your first integration around {virtual_currency}. In CPAlead’s standard publisher postback flow, that value is typically 0. If you need points or in-app currency, it is usually better to calculate them from {payout} inside your own system.

Step 4: Secure the Endpoint Properly

Add a postback password in your CPAlead dashboard and include {password} in the URL. On your server, verify it before you reward the user. This is a simple and effective way to reject unauthorized requests.

If your server only accepts approved IPs, whitelist the relay IP shown inside your CPAlead postback dashboard. That is the outbound IP CPAlead uses for publisher postbacks. If you skip IP whitelisting, password validation becomes even more important.

Your endpoint should also return a fast HTTP 2xx response once the conversion is processed. Slow responses or non-2xx responses can cause retries and postback errors.

Step 5: Test the Postback Before Sending Real Traffic

After you save your postback URL, use the Postback Testing page in your CPAlead dashboard. A good test confirms four things:

The request reaches your server. If it does not, check firewall rules, SSL, IP whitelisting, or your URL format.
The response is HTTP 2xx. Your endpoint should return success quickly after processing the request.
Your user mapping is correct. Confirm that {subid} maps to the right user or wallet in your system.
Duplicate protection works. If the same {lead_id} is sent again, your endpoint should ignore it instead of rewarding the user twice.

After testing, review the Postback Logs page in your CPAlead dashboard. It is the quickest way to confirm the destination URL, response code, and any delivery errors that need to be fixed.

Example PHP Script

Below is a safer starter example than simply updating a balance from {subid} and {payout}. It validates the password, stores {lead_id} uniquely for retry safety, and uses prepared statements instead of raw SQL.

<?php

declare(strict_types=1);

const POSTBACK_PASSWORD = 'replace_with_your_secret';

$subid = trim((string) ($_GET['subid'] ?? ''));
$leadId = (int) ($_GET['lead_id'] ?? 0);
$campaignId = (int) ($_GET['campaign_id'] ?? 0);
$payout = (float) ($_GET['payout'] ?? 0);
$password = (string) ($_GET['password'] ?? '');

if (POSTBACK_PASSWORD !== '' && !hash_equals(POSTBACK_PASSWORD, $password)) {
    http_response_code(403);
    exit('Invalid postback password.');
}

if ($subid === '' || $leadId <= 0) {
    http_response_code(400);
    exit('Missing subid or lead_id.');
}

$pdo = new PDO('mysql:host=127.0.0.1;dbname=your_database;charset=utf8mb4', 'user', 'pass', [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
]);

$pdo->beginTransaction();

try {
    $insert = $pdo->prepare(
        'INSERT INTO cpalead_postbacks (lead_id, user_id, campaign_id, payout, created_at)
         VALUES (:lead_id, :user_id, :campaign_id, :payout, NOW())'
    );
    $insert->execute([
        ':lead_id' => $leadId,
        ':user_id' => $subid,
        ':campaign_id' => $campaignId,
        ':payout' => $payout,
    ]);
} catch (PDOException $e) {
    if (($e->errorInfo[1] ?? null) === 1062) {
        $pdo->rollBack();
        http_response_code(200);
        exit('Duplicate lead ignored.');
    }

    $pdo->rollBack();
    throw $e;
}

$credit = $pdo->prepare('UPDATE users SET balance = balance + :amount WHERE id = :user_id');
$credit->execute([
    ':amount' => $payout,
    ':user_id' => $subid,
]);

if ($credit->rowCount() !== 1) {
    $pdo->rollBack();
    http_response_code(404);
    exit('User not found.');
}

$pdo->commit();
http_response_code(200);
echo 'OK';

If you use a points system instead of cash balance, convert {payout} into your own points ratio before updating the user. For example, if your app uses 100 points per $1.00 earned, calculate that conversion inside your own code rather than depending on a separate macro.

What If You Do Not Want Automatic Crediting?

CPAlead also supports a simpler fallback approach for some publishers: you can prompt the visitor for an email or subID and review completions manually. That can work for very small projects, but it is slower, easier to mis-credit, and much harder to scale. If you want reliable user rewards, automated postback crediting is the better option.

Final Tips

Always pass your own user reference in {subid}.
Always store and dedupe on {lead_id}.
Use {payout} as the main reward input.
Validate {password} before crediting.
Test the URL and review Postback Logs before sending real traffic.

If you follow that pattern, your CPAlead Offerwall postback setup will be much easier to maintain, easier to debug, and far less likely to double-credit users or lose conversions.

Noticed an error or an aspect of this post that requires correction? Please provide the post link and reach out to us. We appreciate your feedback and will address the issue promptly.