Postback tracking helps HilltopAds send event notifications directly to your tracking system. This lets you match impressions, clicks, and conversions to your own records, and see payout amounts when set up.
What is Postback for publishers and how to use it at HilltopAds?
A postback is a server-to-server request that HilltopAds sends to your tracking endpoint whenever an eligible event happens.
Depending on your setup, a postback can notify you about:
A counted impression for popunder traffic, or a counted click for display ads.
A conversion.
The payout for an event, if you include the payout placeholder.
When you receive an impression or click postback, it means that event has been counted. Payout data shows your earnings from CPM impressions or CPA conversions.
Note: Postbacks do not report lost or filtered impressions. The notifications you get depend on which events you choose and the reporting percentage set with your account manager.
How to set up postback tracking
Your HilltopAds account manager will set up the integration for you. Before they start, get your postback endpoint ready and decide which events you want to track.
1. Send your postback URL to your manager
Share the endpoint where your tracking system gets event notifications. For example:
https://website.com/postback?click_uuid={externalid}&payout={payout}&uid=uidIn this example:
click_uuidis the parameter your tracking system uses to receive the identifier.{{clickId}}is replaced with the unique identifier passed through the HilltopAds monetization link.{{payout}}is replaced with the payout amount associated with the reported event.uid– your publisher account ID (you can find it on your dashboard)
Your endpoint might use different parameter names. Send your manager the exact URL your tracking system needs, so they can check the mapping.
If your endpoint needs extra values, like a user ID, agree with your manager on how to map them before setup.
2. Choose which events to receive
HilltopAds offers these reporting options:
Impressions or Clicks
A postback is sent when a popunder impression or a display ad click is counted.
The postback confirms that the event was counted.
Example:
https://website.com/postback?click_uuid={{clickId}}Only conversions
A postback is sent when a conversion occurs. This is useful for publishers working via direct link.
Example:
https://website.com/postback?click_uuid={{clickId}}All events with payouts
Postbacks are sent only for events that generate a payout for you.
For example, if an impression in a CPA campaign does not generate a payout, it will not trigger a postback. If a conversion later brings a payout, you will get a postback for that event.
Example:
https://website.com/postback?click_uuid={{clickId}}&payout={{payout}}Note: You can use the {{payout}} placeholder with any reporting option. The All events (with payout) option only sends notifications for events that generate a payout.
All events
Postbacks are sent for both counted impressions or clicks, and for conversions.
If an impression or click later leads to a conversion, you will get two postbacks with the same clickId: one for the impression or click, and one for the conversion.
Example:
https://website.com/postback?click_uuid={{clickId}}Check that your tracking setup can handle more than one notification for the same identifier.
3. Agree on the reporting percentage
Check with your manager what percentage of eligible events should be sent to your endpoint.
Reporting can be set for a share of events, like 10% or 100%. The default is usually 10% to keep system load low.
Event selection and reporting percentage are separate. Choosing All events does not mean you get 100% of notifications. If sampling is on, your tracking system will only get the agreed share.
Keep this percentage in mind when you compare postback records with your HilltopAds stats.
4. Add tracking parameters to your monetization link
Once the postback is set up, your manager will give you a HilltopAds monetization link and explain which tracking values to use.
https://dengd.com/bC3aV/0.Pf3hp/vpb/m_VLJiZtD/0/3/N/T/QvwrNmTMQ/5kLbTvcJ1WNYDFAx1/NdT-Mf?clickId=PARAM_NAME&sId=PARAM_NAME
The tracking parameters include:
clickId – your unique impression or click ID, used to match postback notifications to your tracking records.
sId – the zone ID.
Replace any example values or placeholders in the monetization link with the right values or dynamic macros from your system, following your manager’s instructions.
Your monetization link and postback URL have different roles:
The monetization link sends traffic to HilltopAds.
The postback URL receives event notifications from HilltopAds.
Always use the monetization link from your manager. Do not use your postback endpoint as a traffic destination.
5. Check the integration
Test the setup with your manager before rolling it out to all your traffic. Make sure that:
Your endpoint receives the selected event notifications.
The returned identifiers match your tracking records.
Payout amounts are received when configured.
Your tracker can handle more than one notification for the same clickId when using All events.
The reporting percentage matches the agreed settings.
If you need help, reach out to your HilltopAds account manager to set up or troubleshoot your publisher postback.