Skip to content
Sign in Open an account
Open an account Sign in
Documentation
Postbacks 8 pages

Postbacks

Macro reference

Every macro you can put in your callback URL, typed, with an example.

On this page 6 sections
  1. The macro set
  2. Signature
  3. Negative on a reversal
  4. Everything is URL-encoded
  5. Build your URL
  6. Macros we do not have

Put these in your callback URL in {braces}. We substitute them at send time and URL-encode every value.

This table is the public contract. Renaming or dropping a macro breaks every integration built against it, so it does not happen.

The macro set#

Macro Type Example Notes
{user_id} string USER_123 Exactly what was passed as userid on the wall
{trans_id} string OFFER19624243-Gw2CpY Unique per conversion. Use this for your own dedupe.
{offer_id} int 19624243 Empty for a conversion from an embedded partner offerwall — there is no offer of ours to name. Do not key on it.
{offer_name} string Badoo%3A%20Dating URL-encoded
{payout_usd} decimal 0.130000 Publisher's share, USD, 6 dp
{currency_amount} decimal 130.00 payout_usd × currency_rate
{app_id} int 10042
{country} string US ISO-2
{ip} string 167.224.159.233 End user's IP at click time
{status} string credited | reversed
{timestamp} int 1754179200 Unix seconds
{signature} string a3f9… See below

Signature#

signature = sha256( trans_id + payout_usd + app_secret )

payout_usd is the string exactly as it appears in the URL — six decimal places, no thousands separator. On a reversal it carries the minus sign and the signature covers it, so a reversal cannot be replayed as a credit.

Runnable verification in five languages: Signature verification.

Negative on a reversal#

{payout_usd} and {currency_amount} are negative when {status} is reversed. {trans_id} is the original transaction's ID, not a new one, so you can find the credit to undo.

If your handler treats amounts as unsigned you will credit a user for a chargeback. Chargebacks & reversals is the page that matters most on this site.

Everything is URL-encoded#

Values are rawurlencoded before substitution. Badoo: Dating arrives as Badoo%3A%20Dating. Your framework decodes query parameters for you; if you are parsing the query string by hand, decode before you use it — and do not decode payout_usd before hashing it, because the signature covers the string as sent.

Build your URL#

Your endpoint

Macros

https://yoursite.com/adnuvora/callback?user_id={user_id}&trans_id={trans_id}&payout_usd={payout_usd}&currency_amount={currency_amount}&status={status}&signature={signature}

Paste the result into Apps → Postback. Parameter names are yours to choose — the macro is what matters, the key beside it is whatever your endpoint reads.

Macros we do not have#

There is no sub_id and no pass-through custom parameter in v1. If you need per-placement attribution, Multiple placements covers the two ways to get it.