Postback Parameters
Whenever one of your users completes an offer, we call the postback URL configured on your placement and substitute the conversion data into it. This is how you credit your users.
How it works
You configure a postback URL on your app placement containing macros wrapped in curly braces. We replace
each macro with its value, URL-encode it, and send the result as an HTTP GET request.
Postbacks are sent as GET requests only. There is no POST mode, and no request body is sent. All data arrives in the query string.
Example postback URL
This is what you would save on your placement:
https://example.com/callbacks/adplusmedia?user_id={user_id}&payout={payout}&reward={reward}&offer_id={offer_id}&offer_name={offerName}&event_id={event_id}&transaction_id={transaction_id}&country={country}&user_ip={user_ip}&status={status}&debug={debug}&sig={sig}Example call we send
GET https://example.com/callbacks/adplusmedia?user_id=user_8837&payout=1.96&reward=117.6&offer_id=4821&offer_name=Monopoly+GO%21&event_id=reach_level_15&transaction_id=884213&country=US&user_ip=203.0.113.24&status=1&debug=0&sig=17b4e2a70d6efe9796dd4c5507a9f9abSupported macros
The following list is exhaustive. Any placeholder not in this table will be delivered to your server literally, unsubstituted.
| Macro | Description | Example |
|---|---|---|
{user_id} |
The unique identifier of your user, exactly as you passed it to the offerwall at click time. | user_8837 |
{payout} |
Your earnings for this conversion, in USD. | 1.96 |
{reward} |
The amount of your virtual currency to credit, already converted using your exchange rate. | 117.6 |
{offer_id} |
The AdPlusMedia ID of the completed offer. | 4821 |
{offerName} |
The name of the completed offer. Note the camelCase spelling. | Monopoly GO! |
{country} |
ISO 3166-1 alpha-2 country code the lead came from. | US |
{user_ip} |
The IP address of the user who completed the offer. | 203.0.113.24 |
{status} |
Whether to credit or reverse. 1 credits the user, 2 is a chargeback. |
1 |
{debug} |
Whether this is a test call or a live conversion. | 1 (test) / 0 (live) |
{event_id} |
Which goal converted, on offers with multiple events. Empty for single-step offers. | purchase |
{transaction_id} |
Our unique ID for this conversion. Use it as your idempotency key. | 884213 |
{sig} |
MD5 hash you use to verify the call really came from us. See Postback Security. | 17b4e2a70d6efe9796dd4c5507a9f9ab |
Multi-step offers
Some offers reward the user across several milestones. Each completed goal fires its own postback, so a
single user on a single offer can generate several credits. Use {event_id} to tell them
apart.
?user_id=user_8837&reward=60&event_id=install_game&transaction_id=884213&status=1
?user_id=user_8837&reward=1200&event_id=reach_level_10&transaction_id=884907&status=1| Offer type | What {event_id} contains |
|---|---|
| Advertiser campaign | The event name configured on the campaign, such as purchase or install_game. |
| Third-party network offer | The provider's own event, goal or transaction token. |
| Single-step offer | Empty. There is only one conversion, so there is nothing to distinguish. |
Do not use {event_id} as your idempotency key. On advertiser campaigns it is an event
name and repeats across every user and every click — deduplicating on it would silently
discard real conversions. Use {transaction_id}, which is unique per conversion.
Macros are case-sensitive. {offerName} is the only camelCase macro. Writing
{offer_name} or {offername} will send that literal text to your server
instead of the offer name.
Credits and chargebacks
The {payout} and {reward} values are always positive. Read {status}
to decide the direction of the transaction.
status | Meaning | Action |
|---|---|---|
1 |
Conversion approved. | Add {reward} to the user's balance. |
2 |
Chargeback. The advertiser reversed the conversion, usually for fraud or an invalid lead. | Subtract {reward} from the user's balance. |
Handle chargebacks. Failing to reverse them means your users keep currency you were never paid for, and the shortfall is deducted from your account balance regardless.
Test postbacks
You can fire a test postback from your placement settings before going live. Test calls are identical in
shape to live ones except that {debug} is 1.
Always branch on {debug} in your handler. Verify the signature and return 200
as normal, but do not credit a real user balance when debug=1.
What we expect back
| Behaviour | Value |
|---|---|
| Method | GET |
| Success response | HTTP status 200 |
| Request timeout | 10 seconds |
| Retries on failure | 5 attempts |
| Retry backoff | 1 min, 5 min, 15 min, 1 hour, 2 hours |
Only an HTTP 200 counts as success. Any other status, a redirect, or a response slower than 10 seconds marks the postback as failed and schedules a retry. Because retries are possible, your handler must be idempotent.
Continue to Postback Security to verify the signature and protect against duplicate credits.