Postback Documentation

Quick start

A publisher postback is an HTTP GET request from CPAlead to your server after a qualifying conversion. Use it to credit cash or points, unlock content, or update your own reports.

1. 1

   Identify your user

   Pass your user ID or a click reference in subid when the user opens an offer.

2. 2

   Save your postback URL

   Enter your receiver URL in Configuration, turn on Postback Enabled, and click Save.

3. 3

   Test your receiver

   Use a safe test user, check the response, and confirm that your system records the reward once.

4. 4

   Check real deliveries

   Open Postback Logs to review delivery results for completed offers.

Tracking URL Setup

Pass your own user ID, wallet ID, transaction ID, or click reference into our tracking URL so the same value comes back to you later in the postback.

Start with the real tracking link from your CPAlead account. Use a value that your server can match to a user. A static subid can identify a page or traffic source for reports, but it cannot tell your server which visitor to reward.

Postback URL Setup

Inside Postback Configuration, save the URL that should receive your conversion notifications. Start with the minimum macros you actually need, then add more fields only if your system uses them.

Replace the example domain and path with your receiver. Keep the placeholders in braces. CPAlead fills them in with URL-encoded conversion values.

The parameter names must match what your receiver expects. For example, user_id={subid} sends your user reference to a receiver that expects user_id.

Macros and aliases

These are the primary CPAlead macros you can place in your URL. They will be replaced with live conversion values when your postback is sent. Use the lowercase names below. Unsupported macros are rejected when you save or test your URL.

{campaign_id}

CPAlead campaign or offer ID for the conversion.

{campaign_name}

CPAlead campaign or offer name.

{subid}

Your primary user ID or click/reference ID passed on the tracking URL. Use a static value only for page, site, or traffic source reporting.

{subid2}

Optional secondary tracking value passed on the tracking URL.

{subid3}

Optional tertiary tracking value passed on the tracking URL.

{idfa}

iOS advertising ID if you passed it on the tracking URL.

{gaid}

Android advertising ID if you passed it on the tracking URL.

{payout}

CPAlead payout amount for the conversion.

{ip_address}

Visitor IP captured on the converting click.

{gateway_id}

Locker or offer-wall tool ID when a CPAlead tool generated the conversion.

{lead_id}

Unique CPAlead lead/conversion ID. Best macro for deduping retries.

{country_iso}

Two-letter country code such as US.

{event_key}

Safe event key such as event_1 for event-based offers. Blank for non-event conversions.

{event_name}

Publisher-safe event name such as Event 1 or a manually reviewed event label. Blank for non-event conversions.

{event_payout}

Publisher payout amount for the completed event. For event-based offers this matches {payout}. Blank for non-event conversions.

{password}

Your saved postback password, if you include {password} in the URL.

{virtual_currency}

Virtual-currency amount from the event. In the standard publisher flow this is typically 0.

Delivery and security

PHP example

This example checks a shared password, prevents duplicate rewards, and records a conversion. Replace the database settings and adapt the user lookup and reward rule to your own system. The saved query data leaves out the password.

<?php
declare(strict_types=1);

/*
 * CPAlead publisher postback example.
 *
 * Recommended CPAlead URL:
 * https://example.com/postback/cpalead.php?subid={subid}&lead_id={lead_id}&campaign_id={campaign_id}&campaign_name={campaign_name}&payout={payout}&password={password}
 *
 * Notes:
 * - {subid} should usually be your internal user ID or click/reference ID when you need to reward one visitor.
 * - A static {subid} is okay for page, site, keyword, or traffic source reporting, but not for visitor-level rewards.
 * - {lead_id} should be stored uniquely so retries do not double-credit a user.
 * - {payout} is the most reliable reward input in the current publisher flow.
 * - {virtual_currency} is currently sent as 0 in the standard publisher postback flow.
 */

const DB_HOST = '127.0.0.1';
const DB_PORT = '3306';
const DB_NAME = 'your_database';
const DB_USER = 'your_user';
const DB_PASS = 'your_password';
const POSTBACK_PASSWORD = 'replace_with_your_secret';

$subid = trim((string) ($_GET['subid'] ?? ''));
$leadId = (int) ($_GET['lead_id'] ?? 0);
$campaignId = (int) ($_GET['campaign_id'] ?? 0);
$campaignName = trim((string) ($_GET['campaign_name'] ?? ''));
$payout = (float) ($_GET['payout'] ?? 0);
$countryIso = strtoupper(substr((string) ($_GET['country_iso'] ?? ''), 0, 2));
$ipAddress = trim((string) ($_GET['ip_address'] ?? ''));
$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.');
}

$dsn = sprintf('mysql:host=%s;port=%s;dbname=%s;charset=utf8mb4', DB_HOST, DB_PORT, DB_NAME);
$pdo = new PDO($dsn, DB_USER, DB_PASS, [
    PDO::ATTR_ERRMODE => PDO::ERRMODE_EXCEPTION,
    PDO::ATTR_DEFAULT_FETCH_MODE => PDO::FETCH_ASSOC,
]);

$pdo->beginTransaction();

try {
    /*
     * Create a table like:
     * CREATE TABLE cpalead_postbacks (
     *   id BIGINT UNSIGNED AUTO_INCREMENT PRIMARY KEY,
     *   lead_id BIGINT UNSIGNED NOT NULL UNIQUE,
     *   user_id VARCHAR(100) NOT NULL,
     *   campaign_id BIGINT UNSIGNED NOT NULL,
     *   campaign_name VARCHAR(255) NOT NULL,
     *   payout DECIMAL(10,4) NOT NULL DEFAULT 0,
     *   country_iso CHAR(2) NULL,
     *   ip_address VARCHAR(45) NULL,
     *   raw_query TEXT NULL,
     *   created_at TIMESTAMP NOT NULL DEFAULT CURRENT_TIMESTAMP
     * );
     */
    $insert = $pdo->prepare(
        'INSERT INTO cpalead_postbacks
            (lead_id, user_id, campaign_id, campaign_name, payout, country_iso, ip_address, raw_query, created_at)
         VALUES
            (:lead_id, :user_id, :campaign_id, :campaign_name, :payout, :country_iso, :ip_address, :raw_query, NOW())'
    );
    $insert->execute([
        ':lead_id' => $leadId,
        ':user_id' => $subid,
        ':campaign_id' => $campaignId,
        ':campaign_name' => $campaignName,
        ':payout' => $payout,
        ':country_iso' => $countryIso ?: null,
        ':ip_address' => $ipAddress ?: null,
        ':raw_query' => json_encode(array_diff_key($_GET, ['password' => true]), JSON_UNESCAPED_SLASHES),
    ]);
} catch (PDOException $e) {
    // MySQL duplicate-key error: the lead was already processed.
    if (($e->errorInfo[1] ?? null) === 1062) {
        $pdo->rollBack();
        http_response_code(200);
        exit('Duplicate lead ignored.');
    }

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

/*
 * Example reward logic:
 * - If you run a cash-back system, you may choose to credit $payout directly.
 * - If you run a points system, convert $payout to your own point value here.
 */
$rewardAmount = $payout;

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

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

$pdo->commit();

http_response_code(200);
echo sprintf(
    'OK lead_id=%d user=%s campaign_id=%d payout=%.4f',
    $leadId,
    $subid,
    $campaignId,
    $payout
);