What Are Postback Macros? Placeholders and URL Parameters

What is a postback macro?

A postback macro is a placeholder in a postback URL, such as {transaction_id} or {user_id}, that the sending platform replaces with a real value every time it calls your server. You save the URL once with the macros in it. When a conversion is credited or reversed, the network fills in each macro and sends the request, so your server receives the actual user ID, reward, status, and signature as ordinary URL parameters.

Macros are the vocabulary of a postback. The postback URL itself, and why it is a server call and not a browser pixel, is covered in What is a postback URL? and server-to-server tracking. This page is about the placeholders.

How postback macros work

A postback URL has two halves in every parameter: a name you pick, and a macro the platform defines.

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

1. You save the template. The left side of each pair (user, tx) is your own parameter name. The right side ({user_id}) is the macro.
2. A conversion happens. A user completes an offer, or a credited offer is reversed later.
3. The platform substitutes. It swaps each macro for the value of that transaction and URL-encodes it.
4. It calls your URL. Your server reads the parameters by your names, checks the signature, and acts on the status.

Filled in, the call above could look like this (illustrative values):

https://yoursite.com/postback?user=4821&tx=9f3a71c2&status=1&reward=250&hash=ba660f3c...

In “postback URL parameters”, the parameter is the name your server reads and the macro is where the value comes from. A macro that is misspelled is usually not replaced, so your server receives the literal text {userid} or an empty value.

The Moonetix postback macro list

These are all the macros Moonetix fills in, taken from the Moonetix postback reference. Use the ones you need, in any order and with any parameter names. Values are URL-encoded.

Sub IDs are the way to carry your own tracking values, such as a traffic source or placement, through to the postback. Click IDs and sub IDs explains how to use them, and the offerwall link builder adds them to a link for you.

Status values

Amounts are never negative: the status tells you whether to add or subtract. The same event can arrive twice after a retry, so store each transaction_id with the last status you processed. How to prevent duplicate reward credits shows the pattern.

The hash macro

{hash} is the HMAC-SHA256, as lowercase hex, of transaction_id:user_id:reward:status (the four values joined with colons), signed with your postback secret key from the app’s Integration tab. HMAC itself is defined in RFC 2104, a keyed hash that proves the sender knew the shared secret. Recompute it on your server from the values exactly as they arrived, and reject the call if it does not match. The postback secret key is different from the link hash salt. What is HMAC? explains the idea, and the postback hash checker lets you test one by hand.

Worked example: one offer, two postbacks

All values here are illustrative. A user with ID 4821 completes an offer. Your app pays 250 Coins for it, and your secret key is example-secret-key.

The credit. Moonetix calls:

https://yoursite.com/postback?user=4821&tx=9f3a71c2&status=1&reward=250&hash=ba660f3c483ffd15b84ce6f386a8296a293e9f6725c7796dc4715964644ce62b

Your server builds the string 9f3a71c2:4821:250:1, computes its HMAC-SHA256 with the key, gets the same hex string, sees no earlier status for 9f3a71c2, adds 250 Coins, and saves status 1.

The reversal. Weeks later the advertiser rejects the conversion. The next call has the same tx=9f3a71c2 and reward=250, but status=2 and a new hash. Your server checks the hash, finds status 1 stored, subtracts 250 Coins, and saves status 2. If the same reversal arrives again, the stored status 2 tells you to skip it.

Without the {transaction_id} macro in your URL, step two is impossible: you would not know which credit to undo.

Macro syntax on other platforms

Placeholders that a platform fills in are common across ad tech, but the syntax and names differ, so copy them from each platform’s own docs. Two official examples, both for click URLs rather than postbacks:

Google documents ValueTrack parameters such as {lpurl} and {gclid} in Set up tracking with ValueTrack parameters. TikTok lists __CAMPAIGN_ID__ (campaign ID) and __CID__ (creative ID) in About UTM Parameters. For how click-side parameters relate to UTM tags, see UTM parameters explained. The lesson for postbacks: a macro from one platform means nothing to another.

Common postback macro mistakes

• Reformatting values before hashing. If your code turns 250 into 250.00 before building the hash string, the signature never matches. Use the values exactly as received.
• Treating status 2 as an error. A reversal is a normal event. Answer it with a 2xx and subtract the reward.
• Logging nothing. Store {event_id} with each call, so support questions can be traced to one request.
• Relying on IP alone. An IP allowlist is a useful extra layer, as postback IP allowlists explains, but always verify the hash too.

Where an offerwall fits

On an offerwall, macros are how the reward reaches your user. Moonetix is a pay-per-result affiliate network: your users complete offers on the Moonetix offerwall, and every credit and reversal arrives at your server as a signed server-to-server postback with these macros filled in. Your server is the only place that should add currency. Ready-made handlers exist for Node.js and Python, and webhook vs postback covers how this differs from JSON webhooks. What {reward} means depends on your virtual currency settings.

Frequently asked questions