Reward Apps Postback

Configure app-specific postback URLs to receive conversion notifications.

Overview

App-level postbacks allow you to set a unique postback URL for each of your apps or websites. When a user completes an offer, we'll send a server-to-server notification to your specified URL with conversion details.

Configuration

To set up app postback:

Go to your Publisher Dashboard
Select your app/website
Edit app settings
Enter your postback URL in the "Postback URL" field
Save changes

Postback URL Format

Your postback URL should accept GET requests with the following parameters as macros:

        https://your-domain.com/postback?user={user_id}&txn={transaction_id}&amount={payout}¤cy={currency}
    

Available Macros

Macro	Description	Example Value
`{user_id}`	Your user ID that was passed to the offerwall	USER123
`{transaction_id}`	Unique transaction identifier	TXN_abc123def456
`{offer_id}`	The offer ID that was completed	12345
`{offer_name}`	Name of the completed offer (URL encoded)	Complete%20Survey
`{payout}`	Reward amount in USD	0.50
`{reward}`	Payout ALREADY converted to your currency via the placement Exchange Rate (e.g. 1.00 × 600 = 600). Negative on reversals.	300
`{currency}`	Currency NAME only (a label, not an amount)	Coins
`{ip}`	User's IP address	192.168.1.1
`{country}`	User's country code	US
`{device}`	User's device type	android
`{status}`	Conversion status — exactly `completed` (credit) or `rejected` (reversal)	completed
`{hash}`	HMAC-SHA256 signature of `user_id + transaction_id + reward + status`, keyed with your Secret Key	9f86d081...
`{sub1}`	Passthrough sub id 1 from the tracking URL (alias: `{aff_sub}`)	campaign1
`{sub2}`	Passthrough sub id 2 from the tracking URL (alias: `{aff_sub2}`)	source_a
`{aff_sub}`	Alias of `{sub1}`	null
`{aff_sub2}`	Alias of `{sub2}`	null
`{aff_sub3}`	Custom sub ID added to the offerwall link	null
`{aff_sub4}`	Custom sub ID added to the offerwall link	null

Example Postback URLs

Basic Example

https://example.com/postback?uid={user_id}&txn={transaction_id}&amount={payout}

Advanced Example with All Parameters

        https://api.example.com/conversions?
            user={user_id}&
            transaction={transaction_id}&
            offer={offer_id}&
            reward={reward}&
            currency={currency}&
            status={status}&
            hash={hash}

Response Requirements

Your server should respond with:

HTTP 200 status code to confirm successful receipt
Response body can be any text (typically "OK" or "SUCCESS")
We'll retry failed requests up to 3 times with exponential backoff

Security

IP Whitelist
All postbacks are sent from one static IP. Whitelist it on your endpoint: 64.226.92.208

Signature Verification ({hash})

Verify {hash} on every request. It is HMAC-SHA256(user_id + transaction_id + reward + status) keyed with your placement Secret Key (shown on the app's integration page). Use the exact values received, in that order, with no separators.

<?php
$expected = hash_hmac('sha256',
    $_GET['user_id'] . $_GET['transaction_id'] . $_GET['reward'] . $_GET['status'],
    $YOUR_SECRET_KEY
);
if (!hash_equals($expected, $_GET['hash'])) {
    http_response_code(403);
    exit('Invalid signature');
}

Reversals

A reversal re-sends the same transaction_id with status=rejected and a negative reward/payout. Add the (negative) value to the user's balance to subtract it.

Testing Your Postback

You can test your postback URL directly from your app's integration page using the "Test Postback" button. This sends a test conversion with sample data.

Example Server Implementation (PHP)

        
<?php
// postback.php

$user_id = $_GET['user_id'] ?? null;
$transaction_id = $_GET['transaction_id'] ?? null;
$payout = $_GET['payout'] ?? 0;
$currency = $_GET['currency'] ?? 'USD';

if ($user_id && $transaction_id) {
    // Credit user account
    creditUserBalance($user_id, $payout, $currency);

    // Log transaction
    logTransaction($user_id, $transaction_id, $payout);

    // Return success
    http_response_code(200);
    echo "OK";
} else {
    http_response_code(400);
    echo "Missing parameters";
}
?>