How to Set Up an Offerwall Postback URL: Macros, Parameters & Testing

A correctly configured postback URL is what turns a completed offer into a credited reward. Get it right and rewards are instant and tamper-proof; get it wrong and users complain that their points never arrived. This guide shows you how to build, secure and test an offerwall postback.

What a postback actually is

A postback (also called a server-to-server or S2S callback) is an HTTP request our servers send to your server the moment a conversion is confirmed. It carries the details of the completion so your backend can credit the right user. Because it's server-to-server, it can't be faked from a user's device. For the bigger picture, read S2S postback explained.

Anatomy of a postback URL

You register a template URL with macros, and we replace the macros with real values at fire time:

https://yoursite.com/postback?user_id={user_id}&txn={transaction_id}&amount={payout}&offer={offer_id}&sig={signature}

Use the exact macro names your network documents — a macro that isn't recognized is sent as literal text, which is a top cause of "missing reward" tickets.

Securing the postback

• Verify the signature. Hash the parameters with your secret key and compare. Reject mismatches.
• Whitelist source IPs where possible.
• Deduplicate by transaction ID. Store processed IDs and ignore repeats so a retried postback never double-credits.
• Return the right status. Reply 200 OK only after you've credited; return an error otherwise so the sender can retry.

What your endpoint should do

1. Validate the signature and required parameters.
2. Check the transaction ID hasn't been processed before.
3. Credit the user's balance.
4. Record the transaction (user, offer, payout, timestamp).
5. Return 200 OK.

Testing before you go live

Never launch an untested postback. Fire a real completion (or a sandbox/test offer) and confirm:

• The request reaches your server with all expected parameters filled (no literal {user_id}).
• The signature validates.
• The user is credited exactly once, even if you replay the same request.
• Your server returns 200 so the conversion isn't retried forever.

Common mistakes

• Reading the wrong parameter name (e.g. expecting user_id when the wall sends subid).
• Crediting before validating the signature.
• No deduplication — retries cause double credits.
• Returning 200 on failure, so genuinely failed credits are never retried.

Frequently asked questions

What's the difference between a postback and a pixel?

A pixel fires from the browser and can be blocked or spoofed. A postback is server-to-server, so it's reliable and tamper-resistant — the standard for rewarded offers.

My users say rewards aren't arriving. Where do I start?

Check that the postback reaches your server, that macros are filled (not literal), and that your signature check isn't rejecting valid calls. Log every incoming postback while debugging.

Should payout or reward amount go in the postback?

Either can, depending on your setup — just be consistent and document which. Many publishers send both the network payout and the user reward.

How do I stop double-crediting?

Deduplicate on the transaction ID: store processed IDs and ignore any repeat before crediting.

Setting up tracking? Grab your keys after you create a publisher account and follow the documentation for exact macro names.