Postback

Postback is a webhook method in the world of internet marketing and traffic arbitrage. This is an HTTP request sent from the advertiser's server (affiliate network; your website) to the tracker server to report the occurrence of a target action: a conversion.

In the context of traffic arbitrage and marketing, postback is used to transmit information about user actions on the website, such as purchasing a product, registration, or performing another target action.

In order for Keitaro to record a conversion in statistics, you need to find the click that the conversion must be recorded for and get the conversion status in the postback. The click ID in the tracker is controlled by the subid parameter, the status is controlled by the status parameter: these are mandatory postback parameters.

The Postback, depending on the type of scheme, is sent:

• By a direct advertiser or an affiliate network.

• By tracker integration scripts (KClient PHP, Tracking script) from sites on third-party hosts, if you're not working with affiliate networks and the traffic goes directly to your website's domain.

• Using JS-Adapter from personal local websites (added as archives in the tracker) or redirected websites. This configuration is applicable when it's your own site, not a site from an affiliate network.

Postback processing

Getting Postback URL

Postback URL is a link to which the offer owner (advertiser or affiliate network) transfers data about the fact of conversion. It contains the tracker server address, Postback key (a unique identifier used for security and authentication of the postback request), and other parameters, among which the mandatory ones are the click identifier subid, the conversion status, and the optional ones are the purchase amount, and other data necessary for tracking and analyzing the effectiveness of advertising campaigns.

If you need Postback URL for affiliate network, please read Affiliate Network Postback.

1. To create an individual link, open Maintenance → Postback URL.

2. Copy the Postback URL and add the necessary parameters from Postback Options.

Postback parameters

• subid (required). Tracker click identificator. Used by the tracker to understand which click to record the conversion.
• status (required). Conversion status.
• tid. Transaction ID. The identifier of the serial number of the target action. For example tid=2 means a second deposit from one player or the purchase of additional training course materials by a person who has already purchased the main material. This is an indication of an additional sale.
• payout (or revenue). Amount of conversion payment. It works for both positive and negative values.
• cost. Conversion cost for CPA and RevShare cost models).
• currency. Payout currency (usd, eur, etc.).
• From sub_id_1 to sub_id_30. Additional free parameters to update the click parameters. Any string and number values are recorded.
• return. Return custom success message. For example, with &return=OK Keitaro will show 'OK'.
• sale_status, lead_status, rejected_status. Read Training for statuses not listed in the tracker section.

WARNING

It is allowed to transmit the following campaign parameters in the postback: keyword, cost, external_id, creative_id, ad_campaign_id and source, but the received data will overwrite the values obtained from the traffic source with the click.

TIP

If subid is already in the tracker, and the postback link contains parameters different from the previous conversion, such postback will overwrite the previous one.

If received identical postbacks, the last postback will not be recorded, the log will show the error Postback 'subid' is duplicate, ignored.

Conversion status

Keitaro supports and displays the following conversion types in its reports:

• Lead — lead. Payment has not yet been confirmed. Revenue for such conversions is displayed in the Revenue (hold) metric.
• Sale — sale. Payment has been confirmed. Revenue for such conversions is displayed in the Revenue (confirmed) metric.
• Rejected — conversion cancellation. Payment has been cancelled. Revenue for such conversions is displayed in the Revenue (rejected) metric.
• Registration — registration. Revenue for such conversions is displayed in the Revenue (registration) metric.
• Deposit — deposit. Revenue for such conversions is displayed in the Revenue (deposits) metric.
• Trash — irrelevant conversion. Revenue for such conversions is displayed in the Revenue (trash) metric.
• Custom conversion types - this setting expands the capabilities of tracking advertising campaigns, allowing you to take into account any conversion types for more accurate analysis of statistics.

1. Processing a postback without specifying status=:

If the postback does not transmit the conversion status, the tracker automatically ignores the conversion, and a corresponding entry is written to the log.

2. Processing new statuses:

If a new status is received in the postback is unknown to the tracker, and the status transformation is not specified in the link, the tracker automatically ignores the conversion, and a corresponding entry is written to the log.

Training for statuses not listed in the tracker

Custom statuses can be transformed to Keitaro statuses.

Keitaro can accept any status in the status= parameter and record it as one of the Keitaro conversion statuses. To implement this, the original conversion status needs to be equated to one of the basic tracker statuses.

• lead_status
• sale_status
• rejected_status
• registration_status
• deposit_status
• trash_status
• custom*_status - where custom* must be replaced with the parameter of the created custom parameter.

Example:

In the Affiliate Network statuses list, registrations are listed as new and registration. Based on the available Keitaro conversion statuses, for the tracker registration is a Lead. It is necessary to specify the corresponding training in the postback link, and when receiving one of the new or registration statuses, the tracker will record the Lead.

status=new&lead_status=new,registration&sale_status=billed&rejected_status=canceled,fake

• Transforms new and registration to lead.

• Transforms billed to sale.

• Transforms cancelled and fake to rejected.

• If you receive a conversion with status=new or status=registration, tracker will record it in reports as Lead, because it is specified in the link status=new&lead_status=new,registration

The same for other statuses, for example Sale.

By getting status=billed&sale_status=billed the tracker understands that billed is recorded as a Sale.

Keitaro stores raw status as "Original status" (status column).

Convert currency

The tracker keeps statistics in one currency specified in Service-Settings-Currency. Pass the currency in the Postback URL in the currency= placeholder, and the tracker will convert the postback payment amount to the currency specified in the settings. Example:

https://example.com/key/postback?status=lead&payout=10&currency=EUR

Now Keitaro does not store payouts in different currencies for each campaign separately. The currency of the statistics is set at the tracker level. The tracker converts the payout amount from the currency specified in the Postback URL.

Sending postback using postback pixel

Postback Pixel is a small piece of code embedded into a webpage that sends conversion data from the site to a tracker. It is suitable for creating custom code to transmit conversion data when a specific action is performed.

1. Create a landing page or offer locally or using preloading. For details on the requirements for creating landing pages and offers, see the Landing page:Local page.

2. Add the Postback Pixel code between the <body>...</body> tags on the index page:

Postback Pixel:

<img src="POSTBACK_URL?subid={subid}&status=lead&payout=10&currency=usd" width="1" height="1" />

Replace POSTBACK_URL with the Postback URL located in Maintenance → Postback URL.

WARNING

The {subid} placeholder in the postback URL works only on index.html or index.php pages.

1. Create an offer or landing page with a redirect action. The URL parameters must include subid={subid}:

2. Add the Postback Pixel code between the <body></body> tags on the page and process the {subid} passed in the subid= parameter in the site URL:

<img src="POSTBACK_URL?subid={subid}&status=lead&payout=10&currency=usd" width="1" height="1" />

The following script serves as an example of a {subid} handler with a pixel:

<script>
        document.addEventListener('DOMContentLoaded', () => {
            const urlParams = new URLSearchParams(window.location.search);
            const subid = urlParams.get('subid');
            const postbackUrl = `POSTBACK_URL?subid=${subid}&status=lead&payout=10&currency=usd`;
            document.getElementById('postback-pixel').src = postbackUrl;
        });
</script>

<img id="postback-pixel" src="" width="1" height="1" />

Replace POSTBACK_URL with the Postback URL located in Maintenance → Postback URL.

Postback FAQ

Why I don't see conversions?

See Postback Troubleshooting page.

How Keitaro converts currency?

Keitaro requests currency exchange rates from an external web service twice daily.

Why sending test postback doesn't work?

Usually affiliate networks don't send real subid. That's why Keitaro ignores these postbacks.

Postback key

That is a unique for each tracker string. It protects Keitaro of receiving non-authorized postbacks.

To change postback key, edit (versions below 10.2) /etc/keitaro/config/tracker.env and set it in the line:

POSTBACK_KEY=CUSTOM_KEY

If the tracker version is 10.2 or higher, edit /etc/keitaro/env/inventory.env:

TRACKER_POSTBACK_KEY=CUSTOM_KEY

Then reconfigure system

kctl tune