Postbacks
How a conversion on somebody else's server gets attached to the click that earned it — the URL to hand a network, the parameters accepted, and why an unrecognised status is never booked as revenue.
A conversion happens on the network's server, minutes or days after the click, with nothing connecting the two except an id you passed them and they pass back. A postback is that call.
#The URL to give a network
Take it from the network's page in UTMCAP rather than writing one, because the version there already carries that network's own parameter names.
There are two forms. The one with the network in the path is better:
https://your-domain.com/postback/{network id}?cid={click_id}&payout={payout}&status={status}
https://your-domain.com/postback?cid={click_id}&payout={payout}&status={status}
The second is a fallback for a network you have not set up yet. It works, but it has to guess which parameter is which; naming the network in the path removes all the guessing, and it is what the page hands you once the network exists.
The braces are the network's macros, not UTMCAP's — every network spells them differently, and their documentation says which. You are telling them where to put their values.
#What has to be in it
The click id, or nothing works. It is the only thing joining the conversion to the click that earned it. Everything else is optional and improves the record; without this there is no record to improve.
You pass it to the network on the offer URL as {click_id}, they store it
against the conversion, and they send it back here.
#Parameter names accepted without configuration
If a network's names are already in these lists, the generic URL works with no setup at all:
| Field | Names tried, in order |
|---|---|
| Click id | click_id clickid cid aff_sub aff_sub1 subid sub_id s1 transaction_id txid |
| Payout | payout amount revenue sum price value |
| Status | status event state type action |
| Conversion id | conversion_id txid transaction_id order_id lead_id |
| Goal | goal event_name conversion_type |
A network whose names are not here gets a mapping on its own page, and then its postback URL is built from that mapping.
Payout is read as a number, so $42.00 and 42,00 both work.
#The four states
Every postback lands in one of four, and the mapping is fixed:
| State | Reported as | Counts as revenue |
|---|---|---|
| approved | approved approve sale lead conversion confirmed ok 1 |
yes |
| rejected | rejected reject declined cancelled canceled trash 0 |
no |
| chargeback | chargeback refund reversal reversed |
no |
| pending | pending hold processing |
no |
Two rules around the edges of that table matter more than the table:
No status at all means approved. A bare postback with nothing but a click id is a network that fires only on conversion, and treating that as pending would leave revenue permanently unbooked.
Anything unrecognised becomes pending. Not approved. A word the mapping has never seen might mean a sale and might mean a refund, and guessing approved turns an unknown into money on a screen somebody is about to make a decision on. It stays pending, visibly, until the mapping is fixed.
That second rule is the usual cause of "revenue is lower than the network
says". Open the conversions log and
look at Status: a column of pending on a network that has approved everything
is a mapping problem, not an approval delay.
Only approved conversions reach Conversions, Revenue, CR, EPC,
ROI and Profit. See the figures, exactly.
#Authenticating the postback
A postback URL is a public address that books revenue, so a network can be
given a shared secret. UTMCAP looks for it as a secret or token parameter,
or an X-Postback-Secret header, and compares it in constant time.
Whether a network's postbacks are authenticated is a column on the networks list, rather than something you have to open each one to find out.
#Telling the traffic source
Once a conversion is recorded, UTMCAP can fire it onward to the traffic source so their optimiser learns which clicks convert. Facebook and TikTok bid differently once they receive conversion signal, and this is the difference between a tracker that records and one that improves what it records.
It is fire-and-forget with retry, deliberately: a slow traffic source must
never delay the 200 the affiliate network is waiting on, because a network
that times out will usually stop sending.
#When nothing is arriving
Work backwards along the chain — each step is a different party, and only one of them is you:
- Does the offer URL carry
{click_id}? Without it the network never had an id to send back. - Has the network been given the postback URL? It has to be configured on their side, and on most networks that is per-offer rather than per-account.
- Is the network firing it? Most show a postback log. A conversion they never sent cannot arrive.
- Did it arrive and get refused? The conversions log records what came in.
A conversion for a click id that does not exist here is recorded and marked rather than dropped — so if the network says it fired and you see nothing, the id it sent is the thing to compare.