Postbacks

Receive real-time notifications when users complete offers. Configure your postback endpoint to automatically credit user accounts.

Overview

When a user completes an offer or survey, Offerlia will send a POST request to your configured postback URL with conversion details. You should process this postback server-side to credit the user's account.

Configuring Your Postback

1. Set Postback URL in App Settings

Go to your app settings and enter your postback endpoint URL. You can use placeholders or query parameters:

https://yourapp.com/postback?user={user_id}&amount={amount}&status={status}

Or with query parameters (automatically appended):

https://yourapp.com/postback

2. Handle GET Requests

Postbacks are sent as HTTP GET requests with parameters in the query string. Make sure your endpoint accepts GET requests.

Postback Parameters

Postbacks are sent as GET requests with the following parameters:

Parameter	Type	Description	Example
`user_id`	String	Your unique user identifier	user_123
`amount`	Integer	Reward amount in your custom currency	150
`status`	Integer	Status code: 1 = approved, 2 = chargeback	1
`transaction_id`	String	Unique transaction identifier	txn_abc123
`offer_id`	String	External offer ID	12345
`offer_name`	String	Name of the completed offer	Survey XYZ
`payout_usd`	Float	Original payout in USD (negative for chargebacks)	2.50
`secure_hash`	String	MD5 hash for verification: MD5(user_id + transaction_id + appSecurityHash)	5d41402abc4b2a76b9719d911017c592

Note: The amount parameter is already converted to your custom currency based on your exchange rate and includes any active bonus percentage.

🔒 Security Hash Verification

Always verify the secure_hash parameter to prevent fraudulent postbacks. The hash is calculated using your app's security hash (found in your app settings).

secure_hash = MD5(user_id + transaction_id + YOUR_APP_SECURITY_HASH)

Status Codes

Status	Description	Amount
`1`	Conversion approved - credit the user	Positive value
`2`	Chargeback - deduct from user balance	Negative value

For chargebacks (status=2), the amount will be negative. Make sure to handle both crediting and debiting user balances.

URL Configuration

You can configure your postback URL in two ways:

Option 1: Using Placeholders

Use placeholders in your URL that will be replaced with actual values:

https://yourapp.com/postback?user={user_id}&reward={amount}&tx={transaction_id}&status={status}

Option 2: Base URL (Auto Parameters)

Provide just the base URL and all parameters will be automatically appended:

https://yourapp.com/postback

// Results in:
https://yourapp.com/postback?user_id=user_123&amount=150&status=1&transaction_id=txn_abc&...

Implementation Example

Handle GET requests in your endpoint:

// Node.js/Express example
const crypto = require('crypto');

const APP_SECURITY_HASH = 'your_app_security_hash_here'; // Get from app settings

app.get('/postback', (req, res) => {
  const { user_id, amount, status, transaction_id, secure_hash } = req.query;
  
  // Validate required parameters
  if (!user_id || !amount || !status || !transaction_id || !secure_hash) {
    return res.status(400).send('Missing required parameters');
  }
  
  // Verify secure_hash
  const expectedHash = crypto.createHash('md5')
    .update(`${user_id}${transaction_id}${APP_SECURITY_HASH}`)
    .digest('hex');
  
  if (expectedHash !== secure_hash) {
    return res.status(401).send('Invalid hash - possible fraud attempt');
  }
  
  // Handle conversion
  if (status === '1') {
    // Approved - credit user
    creditUser(user_id, parseInt(amount));
  } else if (status === '2') {
    // Chargeback - deduct from user (amount is negative)
    debitUser(user_id, Math.abs(parseInt(amount)));
  }
  
  // Log transaction
  logTransaction(transaction_id, user_id, amount, status);
  
  // Return 200 OK
  res.status(200).send('OK');
});

Response Format

Your postback endpoint should return a 200 status code to acknowledge receipt:

// Simple text response
OK

// Or JSON response
{
  "success": true,
  "message": "Postback processed"
}

If your endpoint returns a non-200 status, and you have "Resend failed webhooks" enabled in your app settings, Offerlia will retry the postback up to 5 times with exponential backoff (5min, 15min, 45min, 2h, 6h). You can also manually retry failed postbacks from your app's postback history.