Postback tracking without headaches

A postback is a server-to-server call that tells UluMob a visitor converted. It is what makes CPA campaigns possible and what lets CPM and CPC campaigns show conversions next to cost. Most postback problems come from a handful of causes, and all of them can be found before real money depends on it.

How the click id travels

The whole system rests on one value, the click id.

1. A visitor sees your ad and clicks it, or a popunder opens.
2. UluMob creates a click id (a UUID) and redirects the visitor to your destination URL, replacing {click_id} with that value.
3. Your tracker or landing page stores the click id with the visit.
4. When the visitor converts, your system calls the UluMob postback URL with the same click id.
5. UluMob finds the click, checks the signature and records the conversion. For a CPA campaign, this is also when the charge happens.

If the click id is lost at any step, for example because a redirect drops query parameters or a form does not carry it through, the conversion cannot be matched. Check the full path once by hand: click your own ad, confirm the id arrives at the tracker, and confirm it is still there at the conversion step.

A click can receive conversions for seven days by default. Conversions reported later than that are refused as an unknown click.

Two ways to authenticate: HMAC or key URL

Every postback has to prove it comes from you. Your postback secret, shown under Tracking in the panel, does that in one of two ways.

Signed with HMAC. You compute a hex HMAC-SHA256 over the query string of click_id, conv_type, payout and tx_id, with the keys sorted alphabetically and encoded per RFC 3986, keyed with your secret, and send it as token. The secret never travels in the URL.

/postback?click_id={click_id}&conv_type=A&payout=25.00&tx_id=ORDER-991&token=<hex hmac>

Key URL. You send the secret itself as key. Trackers cannot compute an HMAC per request, so this is the form to paste into a tracker's postback field.

/postback?click_id={click_id}&conv_type=A&payout={payout}&tx_id={tx_id}&key=<your secret>

	HMAC token	Key URL
Secret in the URL	No	Yes
Needs code	Yes, a few lines on your server	No
Best for	Your own backend	Trackers

Treat a key URL as a password: keep it in the tracker and out of shared screenshots. If it leaks, rotate the secret from the Tracking page. Old postbacks stop validating immediately, so update every tracker right after you rotate.

Tracker templates

The Tracking page shows ready-made postback URLs for Voluum, Keitaro, Binom, RedTrack and BeMob. Each one pairs a click parameter for your campaign URL with a postback that uses the tracker's own macro names. UluMob accepts the common aliases, so cid, clickid or externalid all work as the click id, type or goal as the conversion type, and amount, sum or revenue as the payout.

Macro names can change on the tracker's side, so compare the template with your tracker's current documentation before you go live. The full UluMob list is in macros, and the setup steps are in postback setup.

Conversion types

conv_type is a single letter, A by default. You can add more types in the panel, for example A for a registration and B for a deposit, and give each a name. Each type can be switched off, and each type either counts once per click or allows repeats, which suits repeat purchases. A CPA campaign is charged its CPA bid per conversion. The payout you send is your revenue, used for reporting, and does not change what you pay.

Dry run with test=1

Add test=1 to any postback and UluMob runs every check, then answers what would happen without recording or charging anything. The answer includes the campaign id and would_charge, the amount a real call would cost. Use it:

1. after you first set up the tracker,
2. after you rotate the secret,
3. after you change the destination URL or tracker campaign.

Take a real click id from your own test click, fire the postback with test=1, and read the response. A refusal in test mode is not logged, so you can retry freely.

Common refusal reasons

Every refused live postback is logged with its reason. The Tracking page lists refusals from the last seven days with the original query, which is usually enough to see what went wrong.

Reason	Status	What it means	Usual fix
bad_signature	403	The token or key does not match your secret	Check the sort order and encoding of the HMAC, or update the key after a rotation
unknown_click	404	No click with this id, or it is older than the attribution window	Make sure the real click id is passed, not the literal text {click_id} or a tracker's own id
inactive_type	422	The conversion type letter is not set up or is switched off	Add or enable the type, or send the right letter
duplicate	200, ignored	This click already converted for this type, and repeats are off	Expected for retries; allow repeats if the type should count more than once
budget	402	A CPA charge could not be made because the budget or balance is spent	Top up or raise the budget; the tracker can then retry the same postback
rate_limited	429	Too many postbacks from one IP in a short time	Slow the retry loop and respect Retry-After

Two of these deserve a closer look. A duplicate is not an error in the usual sense: trackers often retry, and ignoring the second call is what protects you from being charged twice. A budget refusal, on the other hand, is not marked as a duplicate, so once funds are back the same postback can go through.

A checklist before you launch

• Destination URL contains {click_id}, and a test click shows the real id in the tracker
• Postback URL uses your current secret, as HMAC or key
• The conversion type letter exists and is active
• A test=1 call returns ok with the expected campaign id
• You know where to find refused postbacks

With that done, conversions show up in your reports within minutes. Create an account to get your postback secret.