Postback setup

A postback is a server-to-server call your tracker or backend makes when a visitor converts. It carries the UluMob click ID, so the conversion is matched to the campaign, ad, zone and sub-ID that sent the visitor.

Step 1: pass the click ID

Add {click_id} to every ad's destination URL. UluMob replaces it with a unique ID for each click or open.

https://tracker.example/c?cid={click_id}&zone={zone_id}

{tracking} and {cid} are aliases for the same value. See the macros list.

Step 2: call the postback URL

Your tracking details are at /app/advertiser/tracking. The postback endpoint accepts two ways of proving the call comes from you.

Signed with a token (recommended, and the only way when the platform has key URLs switched off):

https://ulumob.com/postback?click_id=CLICK_ID&conv_type=A&payout=25.00&tx_id=ORDER-991&token=HMAC

Fixed URL with your key (for trackers, which cannot sign each call):

https://ulumob.com/postback?click_id=CLICK_ID&conv_type=A&payout=25.00&tx_id=ORDER-991&key=YOUR_SECRET

The Fixed URL for trackers in the panel already contains your secret. Anyone who sees it, in a server log, a proxy's access log or a screenshot, can post conversions for you: prefer the signed form wherever your code or tracker can compute it, keep the key URL private and rotate the secret if it leaks. UluMob never stores the key value in the refused-postback list. A platform can switch key URLs off; the Tracking screen then says so and only signed postbacks are accepted.

Parameters

Parameter	Also accepted as	Meaning
click_id	cid, clickid, externalid	The UluMob click ID. Required
conv_type	type, goal	A conversion type letter, A to Z. Defaults to A
payout	amount, sum, revenue	Your revenue for this conversion, for reports
tx_id	txid, transaction_id	Your order or transaction ID, up to 128 characters
token		HMAC signature, see below
key		Your postback secret, instead of token
test		1 checks the call without recording it. See Testing postbacks
event		CPA offers: lead, sale, rebill, install, deposit or unsub instead of conv_type. Signed with the others when present
ip, country		CPA offers: the visitor's IP address or country, if your tracker knows it, for the fraud checks

Signing with a token

The token is a hex HMAC-SHA256 keyed with your postback secret. Build it from the four parameters click_id, conv_type, payout and tx_id:

1. Sort them by name.
2. Join them as a URL query string, encoded per RFC 3986.
3. Compute the HMAC of that string with your secret and send it as token.

$p = ['click_id' => $clickId, 'conv_type' => 'A', 'payout' => '25.00', 'tx_id' => 'ORDER-991'];
ksort($p);
$token = hash_hmac('sha256', http_build_query($p, '', '&', PHP_QUERY_RFC3986), $secret);

Sign exactly the values you send. Always include all four keys in the signed string. If you do not send payout or tx_id, sign them with an empty value.

Conversion types

Each account starts with type A. Under Conversion types you can add up to 26 types, one per letter, each with a name, an Active switch and an Allow repeats switch.

• Without repeats, a click counts once per type. Further postbacks for the same click and type are answered ignored.
• With repeats, every postback counts. Send a different tx_id for each conversion.
• A postback for an inactive or unknown type is refused.

Attribution window

A click can receive conversions for 7 days by default. After that, postbacks for it are refused as an unknown click.

What you pay

Only CPA campaigns are charged at the postback, and they pay the campaign's CPA bid, not the payout you report. On CPM, CPC and CPV campaigns, conversions are statistics only. Conversions on clicks marked as fraud are recorded but never charged.

A CPA offer (payouts per event) charges what the event pays in the click's country. Its conversions then wait for the offer's hold, during which you can reject them with a reason and get the charge back. See Reviewing CPA conversions.

Responses

HTTP	Body	Meaning
200	{"status":"ok","charged":"4.000000",...}	Recorded. charged is 0 except on CPA
200	{"status":"ignored","reason":"duplicate"}	Already counted for this click and type
402	reason: budget	CPA charge refused for budget or balance; retry after topping up
403	reason: bad_signature	Wrong token or key
404	reason: unknown_click	Click ID unknown, malformed or past the attribution window
422	reason: inactive_type	Conversion type inactive or not set up
429	reason: rate_limited	Too many calls from one IP

Refused postbacks from the last 7 days are listed under Refused postbacks (7 days) in the panel.

Rotating the secret

Rotate issues a new secret. Old tokens and key URLs stop working at once, so update your tracker and server code straight after.