Postback Integration Guide

A postback (also known as server-to-server or S2S postback) is a real-time notification that MaxPPI sends to your tracking platform when a conversion occurs. This allows you to track conversions in real-time and attribute them correctly to your traffic sources.

What is a Postback?

A postback is a server-to-server notification that MaxPPI sends to your tracking system whenever a conversion occurs. This allows you to track conversions in real-time and attribute them to the correct traffic source without manual intervention.

Quick Setup

1. Log in to your MaxPPI Publisher account
2. Navigate to Postback Settings from the sidebar menu
3. Enter your tracking system postback URL with macros
4. Add optional security token for verification
5. Save your settings and start sending traffic with external click IDs

Complete Configuration

For detailed setup instructions, examples, and troubleshooting, visit the Postback Settings Page.

The Postback Settings page includes:

• Step-by-step configuration guide
• Complete list of available macros
• Multiple real-world URL examples
• How It Works visual flow diagram
• Best practices and tips
• Troubleshooting common issues

Available Macros

Use these macros in your postback URL to receive conversion data:

Macro	Description	Example Value
{click_id}	MaxPPI internal click ID	12345
{external_id}	Your external click ID from tracking URL	abc123xyz
{publisher_id}	Your publisher ID	7
{payout}	Conversion payout amount (USD)	0.50
{country}	User country code (ISO 2-letter)	US
{ip}	User IP address	192.168.1.1
{os}	User operating system	Windows
{device}	Device type	desktop
{offer_id}	Offer ID that converted	42
{smartlink_id}	SmartLink ID used	7
{security_token}	Your security token	secret_token_123

How It Works

The complete postback flow:

1. User Clicks: User clicks your SmartLink with external_id parameter
   Example: https://downlosxa.online/get/ABC123?cid=YOUR_CLICK_ID_789
2. MaxPPI Records: MaxPPI creates a click with both internal and external IDs
   Example: click_id=12345, external_id=YOUR_CLICK_ID_789
3. User Converts: User installs the app and conversion is recorded
4. Postback Fired: MaxPPI sends postback to your URL
   Example: https://yourdomain.com/postback?click_id=YOUR_CLICK_ID_789&payout=0.50&country=US
5. Attribution: Your system receives the postback and matches YOUR_CLICK_ID_789 to attribute the conversion

Postback URL Examples

Generic Tracking System

https://yourdomain.com/postback?click_id={external_id}&payout={payout}&country={country}

With Security Token

https://yourdomain.com/postback?click_id={external_id}&payout={payout}&token={security_token}

Trackier Format

https://yourdomain.trackier.co/acquisition?click_id={external_id}&security_token={security_token}&payout={payout}

Full Details Format

https://yourdomain.com/postback?external_id={external_id}&payout={payout}&country={country}&ip={ip}&os={os}&device={device}&offer_id={offer_id}

Simple Format

https://yourdomain.com/conversion?id={external_id}&amount={payout}

Passing External Click ID

To use postbacks effectively, you need to pass your external click ID to MaxPPI using the cid parameter in your tracking URL:

https://downlosxa.online/get/ABC123?cid=YOUR_CLICK_ID

MaxPPI will store this as external_id and return it in the postback as {external_id} macro.

You can also use these alternative parameters:

• ?clickid=YOUR_CLICK_ID
• ?click_id=YOUR_CLICK_ID
• ?external_id=YOUR_CLICK_ID

All four methods work identically.

Best Practices

1. Use HTTPS: Always use HTTPS for secure data transmission
2. Return HTTP 200 OK: Confirm postback receipt with HTTP 200 status code
3. Implement Idempotency: Use click_id to detect and ignore duplicate postbacks
4. Validate Security Token: Verify postback authenticity if using security tokens
5. Log Postbacks: Keep logs of received postbacks for debugging and reconciliation
6. Handle Timeouts: Set reasonable timeout values (10-30 seconds) for your postback endpoint
7. Use External ID: Always pass external click ID in tracking URL for proper attribution

Troubleshooting

Postbacks Not Received

• Check your postback URL is accessible from the internet
• Verify firewall allows incoming connections from MaxPPI servers
• Ensure your server returns HTTP 200 OK
• Check MaxPPI logs for postback errors

Wrong Data in Postbacks

• Verify macro spelling in your postback URL
• Ensure external_id is passed in tracking URL
• Review Postback Settings configuration

Duplicate Postbacks

• Implement idempotency using click_id
• Use database unique constraints on click_id
• Log and ignore duplicate postbacks

Need Help?

For complete documentation with examples, visit the Postback Settings Page.

You can also contact our support team via:

• Support page in your dashboard
• Email: support@maxppi.com