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.

To register a conversion in Keitaro's statistics, it is necessary to identify the click to which the conversion must be attributed. The tracker's click ID, represented by the parameter subid, is a required parameter for the postback.

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

How Keitaro processes postbacks?

Getting Postback URL

Postback URL is a link through which the offer owner (advertiser, affiliate network) sends data about the completion of a conversion. It contains the tracker server address, Postback key (a unique identifier used for security and authentication of the postback request), other parameters such as click identifier (subid), conversion status, 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.
• 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).
• status (default is sale). Conversion status.
• 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 Custom statuses section.
• ignore_status. List of statuses that must be ignored. Example, ignore_status=ping,test.

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 reports the following statuses:

• lead. Payout is not confirmed. The income on such conversions is displayed in the Revenue (hold) metric.
• sale. Payout is confirmed. The income on such conversions is displayed in the Revenue (confirmed) metric.
• rejected. Payout is cancelled. The income on such conversions is displayed in the Revenue (rejected) metric.
• rebill - Tracker has received a new transaction on subid, already recorded as Sale conversion in the tracker. For example, a repeated deposit. When receiving a unique transaction identifier in the &tid= placeholder in the postback, the tracker reports such conversion as a Rebill. Income from such conversions is summed up in the Revenue (confirmed) metric, in case Rebill is turned on in the offer settings.

Conditions for recording the Rebill status

Keitaro handles upsells when

• Tracker already stores conversion with status=sale on the subid of this click
• Offer allows Rebill. See Offer Settings page.
• Postback includes tid and it's unique.
• Postback has status with value either sale or rebill.

Additional information about statuses

1. Processing postback without specifying status=:

If the postback doesn't include the conversion status, the tracker automatically records the conversion as a sale.

2. Handling of new statuses:

In case a new status is received in the postback, not recognized by the tracker, and no status transformation is specified in the link, the tracker automatically records the conversion as a lead.

Conversion statuses Reg and Dep

TIP

New conversion statuses are available in version 10.3 and above of the tracker. At this stage, to activate this functionality, you need to to update the tracker version.

Registration and Deposit statuses allow for parallel tracking of registrations and sales (deposits) without overwriting the conversion status.

To record conversions with these statuses, accept a postback with the corresponding parameters:

• status=reg — registration. The income on such conversions is displayed in the Revenue (registration) metric.
• status=dep — deposit. The income on such conversions is displayed in the Revenue (deposit) metric.

To record repeated deposits, receiving a unique transaction ID value in the &tid= parameter in the postback is a mandatory condition.

Custom statuses

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.

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" (original_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 /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